QuantumCode

QuantumCode is an interactive quantum algorithm prototyping studio. Build circuits visually, experiment with quantum gates, simulate statevectors, inspect Bloch spheres, and learn common algorithms through guided Academy lessons.

The project combines a Rust quantum engine, an Actix Web API, and a React interface with Three.js visualizations.

---

       

What You Can Explore

• Drag-and-drop circuit construction on multi-qubit wires
• Statevector simulation for circuits up to 12 qubits
• Pauli, Hadamard, phase, rotation, U, controlled, SWAP, and Toffoli gates
• Measurement probabilities and per-qubit Bloch vectors
• Interactive 3D Bloch spheres with phase, angle, and decoherence controls
• Circuit depth and gate-count analysis
• Gate cancellation, fusion, CNOT simplification, and optimization metrics
• OpenQASM 3 import and export workflows
• Built-in OpenQASM examples including teleportation, QFT, error correction, VQE, and ripple-carry addition
• Beginner-to-advanced Academy content covering entanglement, algorithms, error correction, routing, and larger registers
• Undo, redo, zoom, pan, step playback, and responsive analysis panels

Project Layout

quantumcode/
├── core/       Rust quantum engine and WebAssembly bindings
├── server/     Actix Web API
├── ui/         React, TypeScript, Vite, and Three.js application
└── .github/    GitHub Actions deployment workflow

Requirements

• Node.js 20 or newer
• npm
• Rust stable and Cargo
• A modern browser with WebGL support for the 3D Bloch spheres
• wasm-pack only if browser-side Rust/WASM simulation is desired

Run the Interface

Install the frontend dependencies:

cd ui
npm install

Start the development server:

npm run dev

Open http://localhost:3000.

The interface includes a TypeScript simulator and QASM parser fallback, so circuit simulation and supported imports work even when the Rust API or generated WASM package is unavailable.

Run the API

From the repository root, start the Actix server in a second terminal:

cargo run -p quantum-server

The API listens on http://127.0.0.1:8080.

Available routes include:

Method	Route	Purpose
GET	/api/health	Check server status
POST	/api/simulate	Simulate a circuit
POST	/api/optimize	Optimize a circuit
POST	/api/qasm/import	Parse OpenQASM
POST	/api/qasm/store	Store a circuit for export
GET	/api/qasm/export/{circuit_id}	Export stored OpenQASM
POST	/api/tutorial/{name}	Load a built-in tutorial

Build and Test

Build the React application:

cd ui
npm run build

Run the Rust test suite:

cargo test

Generate the Rust WebAssembly package:

cd ui
npm run build:wasm

The WASM command requires the wasm32-unknown-unknown Rust target and wasm-pack.

Using the Academy

Open the Academy panel from the top toolbar. Lessons are organized into three paths:

• Foundations: Bell states and mixed-gate fundamentals
• Algorithms: Teleportation, Grover Search, Shor Period Finding, Deutsch–Jozsa, Bernstein–Vazirani, QFT, and Variational Energy
• Advanced Systems: Four-, five-, six-, eight-, ten-, and twelve-qubit labs covering parity, correction, GHZ states, phase networks, routing, and stress testing

Choose a lesson, move through the steps, and use Auto-Play to watch the circuit grow while the simulator updates.

OpenQASM Examples

Open the OpenQASM 3.0 panel and choose an example from the selector. Click Import to load the selected program into the circuit composer.

The editor supports QuantumCode's gate model directly. More advanced OpenQASM constructs such as arbitrary pulse definitions, custom classical functions, and general control-flow programs may require the Rust parser or adaptation into primitive gates.

GitHub Pages

The UI is deployed by .github/workflows/deploy-pages.yml.

To deploy your own repository:

git remote add origin https://github.com/YOUR_USERNAME/quantumcode.git
git branch -M main
git add .
git commit -m "Deploy QuantumCode"
git push -u origin main

In GitHub, open Settings → Pages and select GitHub Actions as the source.

For the xylium117/quantumcode repository, the expected Pages URL is:

https://xylium117.github.io/quantumcode/

GitHub Pages hosts the static UI only. API-dependent operations need a separately hosted Rust server, while local simulation and supported QASM import use the browser fallback.

Development Notes

• Keep generated directories such as target, ui/node_modules, ui/dist, and generated WASM artifacts out of commits.
• The UI uses Vite's /quantumcode/ base path during Pages builds.
• The Rust simulator stores amplitudes as [real, imaginary] pairs.
• Qubit indices are zero-based throughout the circuit and API representations.

Roadmap

• Complete standards-compliant OpenQASM 3 parsing for custom functions and general control flow
• Generate and publish the optimized WASM package in the deployment workflow
• Add measurement sampling controls and shot histograms
• Add frontend component and simulator integration tests
• Improve hardware-connectivity routing and noise models
• Add saved circuits and shareable project links

See the open issues for a full list of proposed features (and known issues).

License

This repository is licensed under the MIT License. Feel free to use and modify the code as you see fit.

Contributing

1. Fork the repository.
2. Create a feature branch.
3. Make focused changes and add tests where practical.
4. Run npm run build and cargo test.
5. Open a pull request with a concise description of the change.

---