Quantum Curiosity Guide: Interactive Grover's Algorithm Implementation 🔍⚡

A comprehensive quantum computing application featuring a modern React frontend, FastAPI backend, and IBM Quantum hardware integration. Experience Grover's quantum search algorithm with quadratic speedup through an intuitive web interface and deploy seamlessly with Docker and Terraform.

🌟 Overview

This full-stack quantum computing application demonstrates Grover's algorithm - a quantum search algorithm that provides quadratic speedup over classical search methods. While classical computers need O(N) operations to search N items, Grover's algorithm achieves the same result in O(√N) operations using quantum superposition and interference.

🎯 Key Features

🖥️ Modern React Frontend: Interactive web interface with real-time quantum results
🚀 FastAPI Backend: High-performance API with comprehensive quantum operations
🔌 IBM Quantum Integration: Connect to real quantum hardware and simulators
🐳 Docker Deployment: Containerized application with nginx and Python services
🏗️ Terraform Infrastructure: Automated deployment to local and remote environments
📊 Real-time Analytics: Performance metrics and algorithm visualization
🧪 Educational Content: Step-by-step quantum algorithm explanations

🎯 Grover's Algorithm: The Quantum Advantage

The Problem

Imagine searching for a specific item in a massive, unsorted database:

Database queries: Finding records in millions of entries
Cryptography: Testing password combinations
Optimization: Locating optimal solutions
Pattern matching: Finding specific data patterns

Classical vs Quantum Approach

Approach	Time Complexity	Database Size: 1M Items	Operations Needed
Classical	O(N)	1,000,000 items	~500,000 on average
Quantum (Grover)	O(√N)	1,000,000 items	~1,000 operations
Speedup			500x faster!

Real-World Performance Gains

Database Size	Classical Operations	Grover Operations	Speedup Factor
100 items	~50	~8	6x faster
10,000 items	~5,000	~79	63x faster
1 million	~500,000	~1,000	500x faster
1 billion	~500 million	~31,623	15,811x faster

🛠️ Architecture & Implementation

Core Components

quantum/
├── grover_api.py              # FastAPI web service
├── grover.ipynb               # Educational Jupyter notebook
├── test_grover_pytest.py      # Comprehensive test suite
├── test_grover_api.py         # API integration tests
├── test_grover_api_live.py    # Live API testing
├── run_tests.py               # Test runner with multiple modes
├── requirements.txt           # Python dependencies
├── pyproject.toml            # Project configuration
└── local.env                 # Environment variables

Tech Stack

Quantum Computing: Qiskit - IBM's quantum development framework
Web Framework: FastAPI - Modern, fast web API framework
Simulation: Qiskit Aer - High-performance quantum simulators
Testing: pytest - Comprehensive testing framework
Documentation: Interactive API docs with OpenAPI/Swagger

🚀 Quick Start

Prerequisites

Python 3.9+
pip package manager

Installation

Clone the repository
```
git clone <repository-url>
cd quantum
```
Install dependencies
```
pip install -r requirements.txt
```

Start the API server

# Default port 8087 with hot reload
uvicorn grover_api:app --reload --port 8087

# Or run directly with Python (uses default port 8087)
python grover_api.py

# Custom port with hot reload
uvicorn grover_api:app --reload --port 9000

Access the interactive documentation
- API Docs: http://localhost:8087/docs
- Alternative Docs: http://localhost:8087/redoc

Basic Usage

Via Web API

# Search for quantum state "101" in 8-state space
curl -X POST "http://localhost:8087/grover/search" \
     -H "Content-Type: application/json" \
     -d '{
       "target_state": "101",
       "shots": 1000,
       "backend": "simulator"
     }'

Via Python (Direct API)

from grover_api import create_grover_circuit
from qiskit_aer import AerSimulator

# Create quantum circuit for searching "11"
circuit, iterations = create_grover_circuit("11")

# Execute on simulator
simulator = AerSimulator()
job = simulator.run(circuit, shots=1000)
result = job.result()
print(result.get_counts())

Via Jupyter Notebook

jupyter notebook grover.ipynb

🧮 How Grover's Algorithm Works

1. The Oracle Function

The oracle is a quantum function that can recognize target states and "mark" them with a phase flip:

def build_grover_oracle(target_state: str) -> QuantumCircuit:
    """
    Creates oracle that flips phase of target state
    - Input: target_state (e.g., "101")  
    - Output: Quantum circuit that marks the target
    """

Key Insight: The oracle doesn't reveal the answer directly. It invisibly "tags" the correct state so the algorithm can amplify its probability.

2. Amplitude Amplification

Grover's algorithm uses quantum interference to:

Amplify the probability of measuring the correct answer
Suppress probabilities of wrong answers
Iterate this process exactly the right number of times

3. Optimal Iterations

The number of iterations needed is precisely calculated:

optimal_iterations = math.floor(math.pi * math.sqrt(N) / 4)

Where N is the size of the search space (2^num_qubits).

4. Measurement

After optimal iterations, measuring the quantum system yields the target state with high probability (typically >95%).

🏗️ System Architecture

graph TB
    subgraph "Client Environment"
        Browser["🌐 Web Browser"]
    end
    
    subgraph "Application Infrastructure"
        subgraph "Frontend Container"
            React["⚛️ React + Vite<br/>TypeScript"]
            Nginx["🔧 Nginx<br/>Static Server"]
            React --> Nginx
        end
        
        subgraph "Backend Container"
            FastAPI["🚀 FastAPI<br/>Python 3.9+"]
            Qiskit["🔬 Qiskit<br/>Quantum Framework"]
            FastAPI --> Qiskit
        end
        
        subgraph "Container Network"
            Network["🔗 Docker Bridge<br/>quantum-network"]
        end
        
        React -.-> FastAPI
        FastAPI -.-> Network
        Nginx -.-> Network
    end
    
    subgraph "IBM Quantum Cloud"
        IBMQ["☁️ IBM Quantum<br/>Runtime Service"]
        Hardware["🖥️ Quantum Hardware<br/>QPUs"]
        Simulator["💻 Cloud Simulators<br/>Aer Backend"]
        
        IBMQ --> Hardware
        IBMQ --> Simulator
    end
    
    subgraph "Deployment Infrastructure"
        Terraform["🏗️ Terraform<br/>Infrastructure as Code"]
        Docker["🐳 Docker<br/>Container Runtime"]
        
        subgraph "Environment Options"
            Local["🏠 Local Development<br/>localhost:8086/8087"]
            Remote["🌍 Remote Deployment<br/>Digital Ocean + Caddy"]
        end
        
        Terraform --> Docker
        Terraform --> Local
        Terraform --> Remote
    end
    
    Browser --> Nginx
    FastAPI -->|API Key + Instance| IBMQ
    Terraform -.->|Manages| React
    Terraform -.->|Manages| FastAPI
    
    classDef frontend fill:#61dafb,stroke:#333,stroke-width:2px,color:#000
    classDef backend fill:#009639,stroke:#333,stroke-width:2px,color:#fff
    classDef quantum fill:#6f42c1,stroke:#333,stroke-width:2px,color:#fff
    classDef infrastructure fill:#ff6b35,stroke:#333,stroke-width:2px,color:#fff
    classDef environment fill:#28a745,stroke:#333,stroke-width:2px,color:#fff
    
    class React,Nginx frontend
    class FastAPI,Qiskit backend
    class IBMQ,Hardware,Simulator quantum
    class Terraform,Docker infrastructure
    class Local,Remote environment

The system architecture demonstrates the complete quantum computing application stack:

Application Flow

User Interface: Modern React frontend with TypeScript and Tailwind CSS
API Communication: RESTful API calls from frontend to FastAPI backend
Quantum Processing: Qiskit framework handles quantum circuit creation and execution
IBM Integration: Direct connection to IBM Quantum cloud services with API key authentication
Containerization: Docker containers ensure consistent deployment across environments
Infrastructure: Terraform manages the complete deployment lifecycle

Key Architectural Benefits

Scalability: Container-based architecture allows horizontal scaling
Flexibility: Support for both local development and remote production deployment
Security: Isolated container network with controlled external access
Maintainability: Clear separation between frontend, backend, and infrastructure concerns
Educational: Full-stack implementation demonstrates real-world quantum application development

📡 API Reference

Core Endpoints

`GET /`

Root Endpoint - Redirects to interactive API documentation.

Response: 307 redirect to /docs
Purpose: Convenient access to Swagger UI documentation

`POST /grover/search`

Execute Grover's Quantum Search - Run the complete Grover algorithm.

Request Body:

target_state: Binary string (1-3 qubits): "0", "1", "00"-"11", "000"-"111"
shots: Number of measurements (100-10,000)
backend: Quantum backend. Can be "simulator" or real Quantum hardware.

{
  "target_state": "101",
  "shots": 1000,
  "backend": "simulator"
}

Response:

{
  "target_state": "101",
  "num_qubits": 3,
  "optimal_iterations": 2,
  "shots": 1000,
  "success_rate": 96.2,
  "measurements": {
    "000": 12, "001": 15, "010": 8, "011": 9,
    "100": 13, "101": 962, "110": 11, "111": 10
  },
  "circuit_depth": 15,
  "execution_time_ms": 45.67,
  "timestamp": "2024-01-20T10:30:00"
}

`GET /grover/analyze/{target_state}`

Analyze Target State Performance - Get theoretical performance predictions.

Parameters:

target_state: Binary string (1-3 qubits), e.g., "101"

Response:

{
  "target_state": "101",
  "analysis": {
    "num_qubits": 3,
    "search_space_size": 8,
    "optimal_iterations": 2,
    "theoretical_success_rate": 96.1,
    "classical_average_tries": 4.0,
    "quantum_operations": 2,
    "speedup_factor": 2.0
  },
  "performance_comparison": {
    "classical_worst_case": 8,
    "classical_average_case": 4.0,
    "quantum_grover": 2,
    "advantage": "2.0x faster on average"
  }
}

`GET /grover/circuit/{target_state}`

Get Quantum Circuit Information - Retrieve detailed circuit analysis.

Parameters:

target_state: Binary string (1-3 qubits), e.g., "11"

Response:

{
  "target_state": "11",
  "circuit_info": {
    "num_qubits": 2,
    "num_classical_bits": 2,
    "circuit_depth": 10,
    "total_gates": 16,
    "optimal_iterations": 1,
    "transpiled_depth": 8,
    "transpiled_gates": 14
  },
  "circuit_diagram": "ASCII representation of the quantum circuit",
  "gate_summary": {
    "h": 6,
    "x": 4, 
    "cz": 2,
    "measure": 2,
    "barrier": 1
  }
}

`GET /health`

API Health Check - Check API status and basic capabilities.

Response:

{
  "status": "healthy",
  "message": "Grover's Algorithm API is running",
  "version": "1.0.0",
  "max_qubits": 3,
  "available_backends": ["simulator"],
  "description": "Quantum search using Grover's algorithm",
  "docs_url": "/docs",
  "redoc_url": "/redoc"
}

`GET /info`

Comprehensive API Information - Detailed algorithm information and examples.

Response includes:

Algorithm complexity and benefits (O(√N) vs O(N))
Supported qubit configurations (1-3 qubits)
Backend status and availability
Usage examples for different scenarios (1, 2, 3 qubits)
Technical implementation details (oracle, diffusion, gates)
Parameter constraints (shots: 100-10,000)

Error Responses

All endpoints return structured error responses for invalid inputs:

400 Bad Request - Invalid parameters:

{
  "detail": "Target state must be 1-3 qubits"
}

422 Unprocessable Entity - Validation errors:

{
  "detail": [
    {
      "loc": ["body", "target_state"],
      "msg": "Target state must be a binary string",
      "type": "value_error"
    }
  ]
}

500 Internal Server Error - Quantum execution failures:

{
  "detail": "Quantum execution failed: [error description]"
}

🧪 Testing

Test Categories

The project includes extensive testing across multiple dimensions:

Unit Tests: Core algorithm logic
Integration Tests: API endpoint functionality
Performance Tests: Timing and scalability
Error Handling: Edge cases and validation
Concurrency Tests: Multi-request scenarios

Running Tests

# Quick test suite (fast tests only)
python run_tests.py --fast

# All tests including performance
python run_tests.py --all

# Test coverage report
python run_tests.py --coverage

# Specific test categories
python run_tests.py --unit          # Unit tests only
python run_tests.py --integration   # API integration tests
python run_tests.py --performance   # Performance benchmarks
python run_tests.py --errors        # Error handling tests

# Parallel execution (faster)
python run_tests.py --parallel

# Live API testing (requires running server)
python run_tests.py --live

# Check API health
python run_tests.py --health

Test Statistics

546 test lines in main test suite
Parametric testing for all qubit combinations (1-3 qubits)
Performance benchmarks with timing validation
Error case coverage for all invalid inputs
Concurrent request testing for scalability

📊 Performance Characteristics

Quantum Advantage Demonstration

Search Space	Classical Average	Grover Iterations	Success Rate	Speedup
2 states (1 qubit)	1.0 tries	1 iteration	~100%	1x
4 states (2 qubits)	2.0 tries	1 iteration	~100%	2x
8 states (3 qubits)	4.0 tries	2 iterations	~96%	2x

Algorithm Complexity

Time Complexity: O(√N) quantum operations
Space Complexity: O(log N) qubits needed
Success Probability: cos²((2k+1)π/(4√N)) where k is iterations
Optimal Iterations: π√N/4 for maximum success rate

Execution Performance

Single Search: ~50ms average execution time
Concurrent Requests: Supports multiple parallel searches
Circuit Depth: Scales with O(√N) iterations
Gate Count: Linear in number of qubits and iterations

🔬 Educational Resources

Jupyter Notebook Content

The grover.ipynb notebook provides comprehensive educational material:

Problem Introduction: Why quantum search matters
Algorithm Intuition: How quantum superposition enables speedup
Step-by-Step Implementation: Building the quantum circuit
Visual Results: Measurement probability distributions
Performance Analysis: Classical vs quantum comparisons
Mathematical Background: The theory behind the algorithm

Key Learning Concepts

Quantum Superposition: How qubits exist in multiple states simultaneously
Quantum Interference: Using wave properties to amplify correct answers
Oracle Design: Marking target states without revealing them
Amplitude Amplification: The core mechanism of Grover's algorithm
Measurement Statistics: Interpreting probabilistic quantum results

🛡️ Error Handling & Validation

The API includes comprehensive validation:

Input Validation: Binary string format, length constraints
Parameter Bounds: Shot counts (100-10,000), qubit limits (1-3)
Quantum State Validation: Proper quantum state representation
Backend Availability: Simulator accessibility checks
Circuit Construction: Robust oracle and circuit building
Execution Monitoring: Timeout and error recovery

🔧 Configuration

Environment Variables

# local.env
IBM_QUANTUM_API_KEY=your_api_key_here
DEBUG=false
PORT=8087           # Optional: Override default port
LOG_LEVEL=INFO      # Optional: Set logging level (DEBUG, INFO, WARNING, ERROR)

Port Configuration

The API supports flexible port configuration:

# Method 1: Using uvicorn command line (recommended for development)
uvicorn grover_api:app --reload --port 8087  # Default port
uvicorn grover_api:app --reload --port 9000  # Custom port

# Method 2: Using environment variable
export PORT=8090
python grover_api.py  # Will use port 8090

# Method 3: Inline environment variable
PORT=8090 python grover_api.py

# Method 4: Default behavior (no configuration)
python grover_api.py  # Uses default port 8087

Logging Configuration

The API includes comprehensive logging with configurable levels:

# Set logging level via environment variable
export LOG_LEVEL=DEBUG  # DEBUG, INFO, WARNING, ERROR
python grover_api.py

# Inline logging configuration
LOG_LEVEL=DEBUG python grover_api.py

# Combined port and logging configuration
PORT=8087 LOG_LEVEL=DEBUG python grover_api.py

Logging Features:

Centralized Configuration: setup_logging() function manages all logging setup
File Logging: Automatic log file creation (grover_api.log)
Console Logging: Real-time output to stdout
Structured Logs: Timestamp, level, and contextual information
Request Tracing: Complete API request/response logging
Error Tracking: Detailed error logs with stack traces
Performance Metrics: Execution timing for quantum operations
Environment Control: Configurable via LOG_LEVEL environment variable
Initialization Logging: Self-documenting logging setup with debug information

Project Configuration

The pyproject.toml includes:

Dependencies: Quantum and web framework packages
Test Configuration: pytest settings and markers
Code Quality: Black formatting and linting rules
Build Settings: Package metadata and build requirements

🚀 Deployment

Local Development

# Development server with auto-reload (default port 8087)
uvicorn grover_api:app --reload --host 0.0.0.0 --port 8087

# Custom port with hot reload
uvicorn grover_api:app --reload --host 0.0.0.0 --port 9000

# Using environment variable for port
PORT=8090 uvicorn grover_api:app --reload --host 0.0.0.0 --port 8090

Production Deployment

# Production server (default port 8087)
uvicorn grover_api:app --host 0.0.0.0 --port 8087 --workers 4

# Custom port for production
uvicorn grover_api:app --host 0.0.0.0 --port 8080 --workers 4

Docker Deployment

FROM python:3.9-slim
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 8087
CMD ["uvicorn", "grover_api:app", "--host", "0.0.0.0", "--port", "8087"]

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature-name
Write tests for new functionality
Run the test suite: python run_tests.py --all
Submit a pull request

Development Guidelines

Follow PEP 8 style guidelines
Add comprehensive tests for new features
Update documentation for API changes
Maintain backward compatibility where possible

📚 References & Further Reading

Quantum Computing Resources

Qiskit Textbook - Comprehensive quantum computing education
IBM Quantum Experience - Access to real quantum hardware
Grover's Original Paper - "A fast quantum mechanical algorithm for database search"

Algorithm Analysis

Time Complexity: Proves O(√N) vs classical O(N)
Optimality: Grover's algorithm is provably optimal for unstructured search
Applications: Cryptography, optimization, machine learning acceleration

Implementation Details

Oracle Construction: Phase kickback and controlled operations
Amplitude Amplification: Generalization beyond basic search
Error Correction: Handling quantum decoherence and gate errors

🛠️ Development with Lovable

This project is also available on Lovable, a platform for building and editing applications with AI assistance.

How can I edit this code?

There are several ways of editing your application:

Use Lovable

Simply visit the Lovable Project and start prompting.

Changes made via Lovable will be committed automatically to this repo.

Use your preferred IDE

If you want to work locally using your own IDE, you can clone this repo and push changes. Pushed changes will also be reflected in Lovable.

The only requirement is having Node.js & npm installed - install with nvm.

Follow these steps:

# Step 1: Clone the repository using the project's Git URL.
git clone <YOUR_GIT_URL>

# Step 2: Navigate to the project directory.
cd <YOUR_PROJECT_NAME>

# Step 3: Install the necessary dependencies.
npm i

# Step 4: Start the development server with auto-reloading and an instant preview.
npm run dev

Edit a file directly in GitHub

Navigate to the desired file(s).
Click the "Edit" button (pencil icon) at the top right of the file view.
Make your changes and commit the changes.

Use GitHub Codespaces

Navigate to the main page of your repository.
Click on the "Code" button (green button) near the top right.
Select the "Codespaces" tab.
Click on "New codespace" to launch a new Codespace environment.
Edit files directly within the Codespace and commit and push your changes once you're done.

What technologies are used for this project?

This project is built with:

Vite
TypeScript
React
shadcn-ui
Tailwind CSS

How can I deploy this project?

Simply open Lovable and click on Share → Publish.

Can I connect a custom domain to my Lovable project?

Yes, you can!

To connect a domain, navigate to Project > Settings > Domains and click Connect Domain.

Read more here: Setting up a custom domain

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👥 Authors & Acknowledgments

Quantum Computing Lab - Initial implementation
IBM Qiskit Team - Quantum computing framework
FastAPI Contributors - Web framework development

Ready to explore quantum search? Start with the Jupyter notebook for learning, then try the API for practical applications! 🚀⚡

Name		Name	Last commit message	Last commit date
Latest commit History 24 Commits
backend		backend
public		public
src		src
terraform		terraform
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
bun.lockb		bun.lockb
components.json		components.json
eslint.config.js		eslint.config.js
index.html		index.html
nginx.conf		nginx.conf
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.ts		tailwind.config.ts
tsconfig.app.json		tsconfig.app.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts

malminhas/quantum-curiosity-guide

Folders and files

Latest commit

History

Repository files navigation

Quantum Curiosity Guide: Interactive Grover's Algorithm Implementation 🔍⚡

🌟 Overview

🎯 Key Features

🎯 Grover's Algorithm: The Quantum Advantage

The Problem

Classical vs Quantum Approach

Real-World Performance Gains

🛠️ Architecture & Implementation

Core Components

Tech Stack

🚀 Quick Start

Prerequisites

Installation

Basic Usage

Via Web API

Via Python (Direct API)

Via Jupyter Notebook

🧮 How Grover's Algorithm Works

1. The Oracle Function

2. Amplitude Amplification

3. Optimal Iterations

4. Measurement

🏗️ System Architecture

Application Flow

Key Architectural Benefits

📡 API Reference

Core Endpoints

GET /

POST /grover/search

GET /grover/analyze/{target_state}

GET /grover/circuit/{target_state}

GET /health

GET /info

Error Responses

🧪 Testing

Test Categories

Running Tests

Test Statistics

📊 Performance Characteristics

Quantum Advantage Demonstration

Algorithm Complexity

Execution Performance

🔬 Educational Resources

Jupyter Notebook Content

Key Learning Concepts

🛡️ Error Handling & Validation

🔧 Configuration

Environment Variables

Port Configuration

Logging Configuration

Project Configuration

🚀 Deployment

Local Development

Production Deployment

Docker Deployment

🤝 Contributing

Development Guidelines

📚 References & Further Reading

Quantum Computing Resources

Algorithm Analysis

Implementation Details

🛠️ Development with Lovable

How can I edit this code?

Use Lovable

Use your preferred IDE

Edit a file directly in GitHub

Use GitHub Codespaces

What technologies are used for this project?

How can I deploy this project?

Can I connect a custom domain to my Lovable project?

📄 License

👥 Authors & Acknowledgments

About

Topics

Resources

`GET /`

`POST /grover/search`

`GET /grover/analyze/{target_state}`

`GET /grover/circuit/{target_state}`

`GET /health`

`GET /info`

Packages