• Overview
• Features
• Installation
• Usage
• Architecture
• Configuration
• Advanced Features
• Screenshots
• Contributing
• License & Contact

Quantum Whirl is an interactive educational tool designed to visualize and simulate single-qubit quantum mechanics. Unlike standard educational tools that rely on static diagrams, Quantum Whirl provides a real-time, interactive Bloch Sphere and a Quantum Coin Flip experiment that demonstrates superposition, probability amplitudes, and measurement collapse.

• Superposition: Visualize states where the qubit exists in both |0⟩ and |1⟩ simultaneously.
• Measurement Collapse: Watch the state collapse to a basis state upon measurement (coin flip).
• Quantum Noise: Simulate environmental effects like decoherence and entanglement.

• Interactive Bloch Sphere: Rotate and zoom to explore the qubit state vector in 3D space.
• Dynamic State Vector: Real-time updates to the vector position based on θ (theta) and φ (phi) parameters.
• Visual Guides: Equatorial and meridian rings for precise state tracking.

• Real-time Parameters: Adjust probabilities and angles using intuitive sliders.
• Step-by-Step Math: computation panel showing the exact math behind every quantum operation.
• Immersive Design: Particle background, custom cursor trails, and neon aesthetics.

1. Clone the Repository

   git clone https://github.com/muhib-mehdi/quantum-coin-flip.git
   cd quantum-coin-flip

2. Install Dependencies (Optional) If you want to use the included lightweight server:

   npm install

3. Run the Application

   npm start

   Or simply open index.html in your browser.

graph LR
    A[Start] --> B[Explore Page]
    B --> C{Action}
    C -->|Adjust Sliders| D[Update Quantum State]
    C -->|Click Coin| E[Measure Qubit]
    D --> F[Bloch Sphere Updates]
    E --> G[Collapse Wavefunction]
    G --> H["Show Result |0⟩ or |1⟩"]

1. Enter the Lab: Click "Explore" on the landing page.
2. Define State: Use the Quantum Parameters panel on the right to set your qubit's state (e.g., set Alpha to 0.5 for a 25% chance of Heads).
3. Visual Check: Verify the state on the Bloch Sphere at the bottom right.
4. Experiment: Click the Quantum Coin to perform a measurement.
5. Analyze: Watch the Computation Display to see how probability + noise determined the outcome.

The application is built with a separation of concerns between the Physics engine, the Visualization layer, and the User Interface.

graph TD
    subgraph UI [User Interface]
        HTML[index.html]
        CSS[styles.css]
        Script[script.js]
    end

    subgraph Logic [Quantum Core]
        QState[QuantumState Class]
        Math[Probabilities & Phase]
    end

    subgraph Vis [Visualization]
        Three[Three.js Renderer]
        Sphere[Bloch Sphere Mesh]
    end

    HTML -->|User Input| Script
    Script -->|Update Params| QState
    QState -->|State Vector| Sphere
    Sphere -->|Render| HTML
    QState -->|Measurement Result| Script

• quantum.js: Contains the QuantumState class which handles all physics calculations (amplitudes, probabilities, noise simulation).
• script.js: Manages UI interactions, custom cursor effects, and the particle background system.
• Three.js: Used within quantum.js (and inline scripts) to render the 3D Bloch Sphere.

Expand the sections below to understand the adjustable parameters.

The simulation calculates the probability of measuring state $|0\rangle$ using the Born rule, adjusted for environmental noise:

$$ P(|0\rangle) = |\alpha|^2 \times F + \epsilon_{noise} - \gamma_{decoherence} $$

Where:

• $\alpha = \cos(\theta/2)$
• $\beta = e^{i\phi}\sin(\theta/2)$
• $F$ is the Fidelity factor.

The Quantum Whirl Interface showing the Coin (left), Parameters (center), and Bloch Sphere (bottom right).

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request