Metadata-Version: 2.4
Name: quantumsim-edu
Version: 2.0.2
Summary: Educational quantum computing simulator for learning and experimentation
Home-page: https://github.com/Vaiditya2207/quantum-projects
Author: Vaiditya Tanwar
Author-email: vaidityatanwar2207@gmail.com
Project-URL: Bug Reports, https://github.com/Vaiditya2207/quantum-projects/issues
Project-URL: Source, https://github.com/Vaiditya2207/quantum-projects
Project-URL: Documentation, https://github.com/Vaiditya2207/quantum-projects/blob/main/README.md
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Education
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.21.0
Requires-Dist: matplotlib>=3.5.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Provides-Extra: jupyter
Requires-Dist: jupyterlab>=3.0; extra == "jupyter"
Requires-Dist: ipywidgets>=7.0; extra == "jupyter"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# quantumsim-edu: Educational Quantum Computing Simulator

A lightweight, educational quantum circuit simulator designed for learning quantum computing concepts. Built with clarity and modularity in mind, quantumsim provides an intuitive interface for building and simulating quantum circuits.

## How quantumsim Works

quantumsim uses **statevector simulation** to model quantum systems:

### Quantum State Representation
- Quantum states are represented as complex-valued vectors in a 2^n dimensional Hilbert space
- For n qubits, the statevector contains 2^n complex amplitudes
- Each amplitude represents the probability amplitude for a specific computational basis state

### Gate Operations
- Quantum gates are implemented as unitary matrices
- Gate application involves matrix-vector multiplication with the statevector
- Multi-qubit gates use tensor product operations to construct full-dimensional matrices

### Circuit Execution
- Circuits are built using a fluent API that chains gate operations
- The executor applies gates sequentially to evolve the quantum state
- Intermediate states can be inspected for educational purposes

## Features

**Core Simulation Engine:**
- Statevector simulator supporting up to 20 qubits on typical hardware
- Complete quantum gate library: Pauli gates (X, Y, Z), Hadamard (H), Phase gates (S, T), Rotation gates (RX, RY, RZ), Controlled gates (CX, CZ), SWAP gate
- Fluent circuit building API with method chaining
- ASCII circuit visualization for educational clarity

**Educational Tools:**
- Interactive examples demonstrating key quantum algorithms
- Bell state preparation and measurement
- Grover's search algorithm implementation
- Quantum teleportation protocol
- Noise modeling for realistic quantum simulation

## Installation

```bash
pip install quantumsim-edu
```

## 🔧 How to Import and Use

### Basic Imports
```python
# For users who installed via pip install quantumsim-edu
from quantumsim import Circuit, Executor, print_circuit, GATES
from quantumsim.core import Statevector
from quantumsim.noise import DepolarizingChannel
```

## Quick Start

```python
from quantumsim import Circuit, Executor, print_circuit

# Create a 2-qubit circuit
circuit = Circuit(2)
circuit.h(0)        # Hadamard gate on qubit 0
circuit.cx(0, 1)    # CNOT gate: control=0, target=1

# Visualize the circuit
print_circuit(circuit)

# Execute the circuit
executor = Executor()
result = executor.run(circuit)

# Get measurement results
counts = result.measure_all(shots=1000)
print(f"Bell state measurements: {counts}")
# Expected output: {'00': ~500, '11': ~500}
```

## 💻 Advanced Examples

### Grover's Search Algorithm
```python
from quantumsim import Circuit, Executor

def grovers_algorithm(target_state="11"):
    """Grover's algorithm to find a marked state in a 2-qubit system"""
    circuit = Circuit(2)
    
    # Initialize superposition
    circuit.h(0).h(1)
    
    # Oracle - mark the target state |11⟩
    if target_state == "11":
        circuit.cz(0, 1)
    
    # Diffusion operator
    circuit.h(0).h(1)
    circuit.x(0).x(1)
    circuit.cz(0, 1)
    circuit.x(0).x(1)
    circuit.h(0).h(1)
    
    return circuit

# Execute Grover's algorithm
circuit = grovers_algorithm()
result = Executor().run(circuit)
counts = result.measure_all(1000)
print(f"Grover's results: {counts}")  # Should favor |11⟩
```

### Quantum Noise Simulation
```python
from quantumsim.noise import DepolarizingChannel

# Create a Bell state
circuit = Circuit(2)
circuit.h(0).cx(0, 1)

executor = Executor()
clean_state = executor.run(circuit)

# Apply noise
noise = DepolarizingChannel(p=0.1)  # 10% noise
noisy_state = noise.apply_stochastic(clean_state)

# Compare measurements
clean_counts = clean_state.measure_all(1000)
noisy_counts = noisy_state.measure_all(1000)

print("Clean measurements:", clean_counts)
print("Noisy measurements:", noisy_counts)
```

# Create a Bell state circuit
circuit = Circuit(2)
circuit.h(0)        # Apply Hadamard to qubit 0
circuit.cx(0, 1)    # Apply CNOT with control=0, target=1

# Execute the circuit
executor = Executor()
final_state = executor.run(circuit)

# Measure the result
measurement_counts = final_state.measure_all(shots=1000)
print("Measurement results:", measurement_counts)
# Expected: {'00': ~500, '11': ~500} (Bell state superposition)
```

## License

MIT License - Free for educational and research use.
