{"id":33619418,"url":"https://github.com/quantum4j/quantum4j","last_synced_at":"2026-06-12T09:31:03.992Z","repository":{"id":325197603,"uuid":"1100229794","full_name":"quantum4j/quantum4j","owner":"quantum4j","description":"Quantum4J brings quantum programming to Java with a full Quantum Software Engineering stack — circuits, simulators, compiler passes, QASM support, and enterprise-grade extensibility.","archived":false,"fork":false,"pushed_at":"2026-04-09T02:46:02.000Z","size":3522,"stargazers_count":16,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-09T04:27:03.335Z","etag":null,"topics":["java","java-library","jdk","openqasm","openqasm-lang","qasm","qiskit","quantum","quantum-algorithms","quantum-computing","quantum-microservice","quantum-sdk","quantum-simulator","quantum4j","qubits","spin-qubits","statevector","transpiler"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/quantum4j.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-20T02:27:43.000Z","updated_at":"2026-03-31T18:38:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/quantum4j/quantum4j","commit_stats":null,"previous_names":["vijayanandg/quantum4j","quantum4j/quantum4j"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/quantum4j/quantum4j","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quantum4j%2Fquantum4j","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quantum4j%2Fquantum4j/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quantum4j%2Fquantum4j/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quantum4j%2Fquantum4j/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/quantum4j","download_url":"https://codeload.github.com/quantum4j/quantum4j/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/quantum4j%2Fquantum4j/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34238711,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-12T02:00:06.859Z","response_time":109,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["java","java-library","jdk","openqasm","openqasm-lang","qasm","qiskit","quantum","quantum-algorithms","quantum-computing","quantum-microservice","quantum-sdk","quantum-simulator","quantum4j","qubits","spin-qubits","statevector","transpiler"],"created_at":"2025-12-01T10:05:48.857Z","updated_at":"2026-06-12T09:31:03.987Z","avatar_url":"https://github.com/quantum4j.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Quantum4J: A Modern Java Quantum Computing SDK  \n**Lightweight • Extensible • JVM-Native • Engineering-First**\n\n![Build](https://github.com/quantum4j/quantum4j/actions/workflows/maven.yml/badge.svg)\n![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)\n![Java](https://img.shields.io/badge/Java-17%2B-blue)\n![Maven Central](https://img.shields.io/maven-central/v/com.quantum4j/quantum4j.svg)\n![Stars](https://img.shields.io/github/stars/quantum4j/quantum4j.svg?style=flat)\n\n---\n\n⚠️ **Official Quantum4J Repository**\n\nThis is the **ONLY official Quantum4J project**.  \nAny other repositories using the Quantum4J name or branding are **independent forks and not affiliated**. Quantum4J does NOT distribute executables (.exe), including inside ZIP archives.\nOfficial artifacts are ONLY published via Maven Central and this repository:\nhttps://github.com/quantum4j/quantum4j\n\n---\n\nQuantum4J is a modern, modular, and fully JVM-native quantum computing SDK designed to bring  \n**Quantum Software Engineering (QSE)** into the Java ecosystem.\n\nWhile most quantum tools today focus on research workflows inside notebooks, Quantum4J is built for the  \n**next phase of quantum evolution** — integrating quantum logic into real software systems, microservices,  \nenterprise pipelines, CI/CD, and cloud environments.\n\nQuantum4J is:\n\n- A **clean quantum circuit API** for engineers  \n- A **deterministic statevector simulator**  \n- A **QASM-compatible** execution model  \n- A **JVM-first architecture** ready for enterprise use  \n- A **foundation** for future quantum engineering tools (testing, orchestration, cloud execution)\n\nQuantum4J is **100% open-source**, **dependency-free**, and currently runs circuits up to ~**25 qubits** (memory bound).\n\n---\n\n# 🚀 Why Quantum4J?\n\nModern quantum development is dominated by research tools.  \nQuantum4J instead focuses on **engineering requirements**:\n\n- Deterministic, testable simulation  \n- Clean modular API and package structure  \n- Version-controlled quantum circuits in normal code repos  \n- Backend-agnostic QASM export/import  \n- JVM-native integration (Java, Kotlin, Scala)  \n- Ready for microservices, cloud deployment, and CI/CD pipelines  \n- A foundation for future orchestration, debugging, and test frameworks\n\nQuantum4J aims to become the **engineering layer** of the quantum software stack — the place where quantum meets real-world systems.\n\n---\n\n# ✨ Features\n\n## ✔ Full Standard Gate Set\n- **Single-qubit:** X, Y, Z, H, S, T  \n- **Rotation gates:** RX(θ), RY(θ), RZ(θ)  \n- **Controlled gates:** CX, CZ, CH  \n- **Two-qubit:** SWAP, iSWAP  \n- **Three-qubit:** CCX (Toffoli)\n\n## ✔ State-Vector Simulator\n- High-performance N-qubit statevector backend  \n- Supports 1-, 2-, and 3-qubit unitaries  \n- Custom `Complex` math implementation  \n- Deterministic and sample-based execution modes\n\n## ✔ Measurements\n- `measure(q, c)`  \n- `measureAll()`  \n- Classical registers  \n- Deterministic or sampled measurement behavior\n\n## ✔ OpenQASM Import/Export\n- Strict OpenQASM 2.0 importer (whitespace/comments tolerant)  \n- Deterministic OpenQASM 2.0 exporter  \n- Round-trip tests (import → export → import) for correctness\n\n## ✔ Transpiler \u0026 Optimizations\n- PassManager with composable passes  \n- Swap, CX→CZ, U3 decomposition  \n- Rotation fusion, CX cancellation, gate inversion, commutation  \n- Default transpiler pipeline for safe round-tripping\n\n## ✔ Extensible Backends (Pluggable)\n- Built-in: `STATEVECTOR` simulator  \n- Hardware hook via `BackendFactory` (IonQ example)  \n- Future-ready slots for density/stabilizer/GPU/hardware backends\n\n## ✔ Circuit Visualization\n- ASCII renderer (deterministic, multi-qubit routing)  \n- SVG renderer for publication-quality diagrams\n\n## ✔ Example Circuits + Test Suite\n- Bell, GHZ, Toffoli, SWAP/iSWAP, rotations, QFT, Deutsch, Grover, teleportation  \n- Extensive JUnit 5 suite for gates, QASM, transpiler, visualization, backend layers\n\n---\n\n# 📦 Installation\n\n## Maven (Maven Central)\n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.quantum4j\u003c/groupId\u003e\n    \u003cartifactId\u003equantum4j\u003c/artifactId\u003e\n    \u003cversion\u003e1.3.2\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Gradle\n```gradle\nimplementation 'com.quantum4j:quantum4j:1.3.2'\n```\n\n## From Source\n```bash\ngit clone https://github.com/quantum4j/quantum4j.git\nmvn test\n```\n\n---\n\n# 🚀 Quick Start Example\n\n## 🧪 Hello Quantum (minimal example)\n\n```java\nQuantumCircuit qc = QuantumCircuit.create(1).h(0).measureAll();\nResult r = qc.run(RunOptions.withBackend(BackendType.STATEVECTOR).withShots(200));\nSystem.out.println(r.getCounts());  // roughly {0≈100, 1≈100}\n```\n\nThis is the smallest runnable example to get started quickly.\n\n➡️ See `/src/main/java/com/quantum4j/examples` for 25+ runnable demos.\n\n### Create a Bell State\n\n```java\nimport com.quantum4j.core.circuit.QuantumCircuit;\nimport com.quantum4j.core.backend.*;\n\npublic class BellState {\n    public static void main(String[] args) {\n        QuantumCircuit qc = QuantumCircuit.create(2)\n                .h(0)\n                .cx(0, 1)\n                .measureAll();\n\n        Result r = qc.run(RunOptions.withBackend(BackendType.STATEVECTOR).withShots(1000));\n        System.out.println(r.getCounts());\n    }\n}\n```\n\n**Sample Output**\n```\n{00=502, 11=498}\n```\n\n---\n\n# 🔺 Toffoli (CCX) Example\n\n```java\nQuantumCircuit qc = QuantumCircuit.create(3)\n    .x(0)\n    .x(1)\n    .ccx(0, 1, 2)\n    .measureAll();\n\nResult r = qc.run(RunOptions.withBackend(BackendType.STATEVECTOR).withShots(1000));\nSystem.out.println(r.getCounts());\n```\n\nExpected:\n```\n{111=1000}\n```\n\n---\n\n# 📤 Export to QASM\n\n```java\nQuantumCircuit qc = QuantumCircuit.create(2)\n    .h(0)\n    .cx(0, 1)\n    .measureAll();\n\nString qasm = QasmExporter.toQasm(qc);\nSystem.out.println(qasm);\n```\n\nOutput:\n```\nOPENQASM 2.0;\ninclude \"qelib1.inc\";\nqreg q[2];\ncreg c[2];\n\nh q[0];\ncx q[0], q[1];\nmeasure q[0] -\u003e c[0];\nmeasure q[1] -\u003e c[1];\n```\n\n---\n\n# 🔗 Using Quantum4J in Spring Boot / REST APIs\n\nQuantum4J is designed to fit naturally into backend systems and microservices.\n\n```java\n@RestController\n@RequestMapping(\"/api/quantum\")\npublic class QuantumController {\n\n    @GetMapping(\"/bell\")\n    public Map\u003cString, Integer\u003e bell() {\n        QuantumCircuit qc = QuantumCircuit.create(2)\n                .h(0)\n                .cx(0, 1)\n                .measureAll();\n\n        Result result = qc.run(RunOptions.withBackend(BackendType.STATEVECTOR).withShots(1000));\n        return result.getCounts();\n    }\n}\n```\n---\n# Running on Real Quantum Hardware\n\nQuantum4J supports pluggable backends. The default is STATEVECTOR simulation. Hardware backends are optional and only used if you register them manually (IonQ example below):\n\n1) Register a hardware backend:\n```java\nBackendFactory.register(\n    BackendType.HARDWARE,\n    new IonQBackend(System.getenv(\"IONQ_API_KEY\"))\n);\n```\n\n2) Execute using the hardware backend:\n```java\nResult r = circuit.run(RunOptions.withBackend(BackendType.HARDWARE).withShots(500));\nSystem.out.println(r.getCounts());\n```\n\n3) IonQ authentication\n- Set env var `IONQ_API_KEY` to your IonQ API key.\n- The backend submits OpenQASM 2.0 to IonQ's REST API.\n\n4) Cost and noise notice\n- Real hardware runs may incur cloud costs.\n- Hardware results are subject to device noise and queue times.\n\n5) Example\n- See `com.quantum4j.examples.GroverHardwareExample` for an end-to-end IonQ submission sample.\n\n## Feature Highlights (recap)\n- OpenQASM 2.0 import/export (strict importer, deterministic exporter).\n- Pluggable backends: STATEVECTOR simulator built-in; optional hardware via BackendFactory (IonQ example).\n\n\n---\n\n# 🧱 Architecture Overview (Code-Level)\n\n| Module     | Description                                       |\n|------------|---------------------------------------------------|\n| `circuit/` | Circuit objects, instructions, fluent builder     |\n| `gates/`   | Gate definitions (1, 2, 3 qubit)                  |\n| `math/`    | Complex arithmetic + state-vector implementation  |\n| `backend/` | Execution backend (statevector + pluggable HW)    |\n| `qasm/`    | QASM importer/exporter                            |\n| `visualization/` | ASCII + SVG circuit rendering               |\n| `transpile/` | PassManager + decomposition/optimization passes |\n| `examples/`| Ready-to-run examples                             |\n| `tests/`   | JUnit 5 test suite                                |\n\n---\n\n# 🧪 Test Suite\n\nRun tests:\n```bash\nmvn test\n```\n\n---\n\n# ⚡ Performance Notes\n\n25 qubits is the upper bound on typical JVM memory for the statevector backend.\n\n---\n\n# 🗺️ Roadmap\n\n- Noise models \u0026 density matrix backend  \n- Stabilizer backend  \n- GPU/offloaded simulation  \n- Additional compiler passes and schedulers  \n- Expanded hardware connectors (IBM, Braket, Rigetti)  \n- Cloud execution services  \n\n---\n\n# 🧑‍💻 Contributing\n\nWe welcome:\n- Pull requests  \n- Issue reports  \n- New gate implementations  \n- Example circuits  \n- Academic extensions  \n\nPlease use the **Google/IntelliJ Java style guide**.\n\n---\n\n# 📄 License\n\nApache License 2.0  \nCopyright (c) 2025 Vijaya Anand Geddada\n\n---\n\n# 🏢 Maintainer\n\n**Vijay Anand Geddada**  \nCreator – Quantum4J  \n20+ years enterprise engineering leadership  \nCloud-native • Microservices • Java • Spring • Quantum\n\n# ⭐ Star the Repo\n\nIf you find this useful: https://github.com/quantum4j/quantum4j\n\n---\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquantum4j%2Fquantum4j","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fquantum4j%2Fquantum4j","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fquantum4j%2Fquantum4j/lists"}