Hybrid Quantum Circuit Simulator (qsim)

# Hybrid Quantum Circuit Simulator (qsim)

## PROJECT OVERVIEW

This project implements a hybrid quantum circuit simulator that efficiently handles various types of quantum circuits by dynamically selecting the most appropriate simulation method. The architecture integrates:

1. Block Simulation - For structured circuits with localized operations
2. Tensor Network Methods - For circuits with high entanglement
3. Sparse Representation & Hash Maps - For tracking nonzero state amplitudes
4. Parallelization and GPU Acceleration - For efficient handling of large systems

The simulator supports arbitrary qudit dimensions, not just qubits, making it versatile for simulating a wide range of quantum systems.

## ARCHITECTURE

The simulator is organized around these core components:

- **Core Components** (`qsim/core/`): Basic building blocks like `QuantumCircuit` and `Qudit`
- **Quantum Gates** (`qsim/gates/`): Various gate implementations (Hadamard, Phase, Permutation, Controlled)
- **Quantum State Representations** (`qsim/states/`): `StateVector`, `SparseStateVector`, `TensorNetworkState`
- **Circuit Analysis** (`qsim/analysis/`): `CircuitAnalyzer` for determining optimal simulation strategies
- **Execution Management** (`qsim/execution/`): `HybridExecutionManager` and `HybridQuantumSimulator`
- **Utilities** (`qsim/utils/`): Helper functions and circuit builders
- **Benchmarks** (`benchmarks/`): Performance benchmarking tools for evaluating simulator efficiency
- **Examples** (`examples/`): Example scripts demonstrating simulator capabilities

The system dynamically analyzes circuits to determine whether to use block simulation (for sparse/localized circuits), tensor networks (for highly entangled circuits), or other methods based on circuit properties.

## CODE ORGANIZATION

The project follows a modular package structure:

```
qsim/
├── __init__.py       # Package initialization and exports
├── main.py           # Main demonstration script
├── core/             # Core components
│   ├── __init__.py
│   ├── circuit.py    # QuantumCircuit implementation
│   ├── config.py     # Configuration settings
│   ├── constants.py  # Constant values
│   └── qudit.py      # Qudit implementation
├── gates/            # Quantum gate implementations
│   ├── __init__.py
│   ├── base.py       # Base Gate class
│   ├── hadamard.py   # Hadamard gate
│   ├── phase.py      # Phase gate
│   ├── permutation.py # Permutation gate
│   ├── controlled.py # Controlled gate
│   └── multi_controlled.py # Multi-controlled gate
├── states/           # Quantum state representations
│   ├── __init__.py
│   ├── base.py       # Base QuantumState class
│   ├── state_vector.py # Dense state vector
│   ├── sparse_state_vector.py # Sparse state vector
│   └── tensor_network_state.py # Tensor network state
├── analysis/         # Circuit analysis
│   ├── __init__.py
│   └── circuit_analyzer.py # Circuit analysis tools
├── execution/        # Execution management
│   ├── __init__.py
│   ├── hybrid_execution_manager.py # Hybrid execution
│   └── simulator.py  # Main simulator class
├── utils/            # Utility functions
│   ├── __init__.py
│   └── circuit_builders.py # Common circuit builders
docs/                 # Documentation
└── components.md     # Core components and their interfaces
examples/             # Example scripts
├── __init__.py
├── README.md         # Examples documentation
├── basic_usage.py    # Basic usage examples
├── grovers_search.py # Grover's search algorithm implementation
├── hybrid_simulation_benchmark.py # Benchmark for hybrid simulation
├── multi_qudit_simulation.py # Multi-qudit simulation examples
├── quantum_error_correction.py # Quantum error correction examples
├── quantum_phase_estimation.py # Quantum phase estimation algorithm
└── variational_quantum_eigensolver.py # VQE algorithm implementation
benchmarks/           # Performance benchmarks
├── scaling_ghz.py    # GHZ state scaling benchmark
└── plots/            # Directory for benchmark plots
tests/                # Test suite
├── __init__.py
├── README.md         # Testing documentation
├── test_analysis.py  # Tests for analysis module
├── test_bell_state.py # Tests for Bell state creation
├── test_circuit_builders.py # Tests for circuit builders
├── test_core.py      # Tests for core components
├── test_execution.py # Tests for execution management
├── test_gates.py     # Tests for quantum gates
├── test_generalized_bell_state.py # Tests for generalized Bell states
├── test_grovers_search.py # Tests for Grover's search implementation
├── test_multi_controlled_gate.py # Tests for multi-controlled gates
└── test_states.py    # Tests for quantum state representations
```

Additional project files:
- `setup.py` and `pyproject.toml` - Package configuration
- `README.md` - Project documentation
- `LICENSE` - MIT license
- `Makefile` - Development tasks
- `pytest.ini`, `.flake8`, `mypy.ini` - Testing and linting configuration
- `run_tests.py` - Script to run tests
- `.python-version` - Python version specification
- `uv.lock` - Dependency lock file

## CODING STANDARDS

### Naming Conventions

- Classes: PascalCase (e.g., `StateVector`, `HadamardGate`)
- Methods/Functions: snake_case (e.g., `apply_gate`, `get_probabilities`)
- Variables: snake_case (e.g., `qudit_index`, `amplitude`)
- Constants: UPPER_SNAKE_CASE (e.g., `TENSOR_NETWORK_THRESHOLD`)
- Modules: snake_case (e.g., `circuit_analyzer.py`, `state_vector.py`)

### Type Annotations

Use Python type hints for all function/method signatures:

```python
def get_probability(self, index: int) -> float:
    """Get the probability of measuring a specific computational basis state."""
```

### Documentation

- All classes and public methods must have docstrings using Google-style format
- Include Args, Returns, and Raises sections where appropriate
- Complex algorithms should have inline comments explaining the approach
- Module-level docstrings should describe the purpose of the module

Example docstring:

```python
def apply_gate(self, gate: Gate) -> None:
    """
    Apply a quantum gate to the state vector.
    
    Args:
        gate: The quantum gate to apply
        
    Raises:
        ValueError: If the gate acts on qubits not in the system
    """
```

### Error Handling

- Use specific exception types with informative error messages
- Check for invalid inputs early in functions
- Log failures with appropriate severity levels

### Code Formatting

- 4 spaces for indentation (no tabs)
- Maximum line length of 100 characters
- Group imports by standard library, third-party, and local modules
- Add blank lines to separate logical sections
- Use Black and isort for consistent formatting

### Testing

- Write unit tests for all components using pytest
- Test files should be in the `tests/` directory
- Test files should be named `test_*.py`
- Test classes should be named `Test*`
- Test methods should be named `test_*`

### Performance Considerations

- Prefer NumPy vectorized operations over explicit loops
- Use sparse representations for states with many zero amplitudes
- Leverage GPU acceleration for tensor operations when available
- Avoid unnecessary object creation within tight loops
- Use benchmarking tools to identify performance bottlenecks

## QUANTUM COMPUTING CONVENTIONS

### State Representation

- State vectors use the computational basis ordering: |00...0⟩, |00...1⟩, ..., |11...1⟩
- For multi-qudit systems, the rightmost qudit has the lowest significance in indices
- States are normalized such that the sum of probability amplitudes squared equals 1

### Gates and Operations

- Gates are represented by their matrix form in the computational basis
- Multi-qudit gates specify their target qudits explicitly
- The simulator supports qudits of arbitrary dimensions (not just qubits)
- Controlled operations specify both control qudits and their required values

### Multi-Qudit Support

- The system supports qudits of arbitrary dimension (d ≥ 2)
- Qudits can have different dimensions within the same circuit
- Gate implementations handle arbitrary qudit dimensions
- Special handling for higher-dimensional generalizations of standard gates

## BENCHMARKING

The project includes comprehensive benchmarking tools to evaluate performance:

- **GHZ State Scaling**: Tests how well the simulator scales with increasing system size
- **Hybrid Simulation Benchmark**: Compares different simulation methods on various circuit types
- **Performance Metrics**: Measures execution time, memory usage, and simulation accuracy
- **Visualization**: Generates plots to visualize performance characteristics

## DEVELOPMENT WORKFLOW

### Environment Setup

- Use uv for package management and virtual environments
- Install development dependencies with `uv pip install -e ".[dev]"` or `make dev-setup`
- Run tests with `pytest` or `make test`
- Format code with `black` and `isort` or `make format`
- Lint code with `flake8` and `mypy` or `make lint`

### Running Examples and Benchmarks

- Basic examples: `python -m qsim.main` or `python examples/basic_usage.py`
- Advanced examples: `python examples/quantum_phase_estimation.py`, etc.
- Run all examples: `make examples`
- Run benchmarks: `python benchmarks/scaling_ghz.py --output-dir=benchmarks/plots`

### Continuous Integration

- Run tests before committing changes
- Ensure all linting checks pass
- Keep test coverage high

## IMPLEMENTATION PRIORITIES

1. Correctness - The simulator must produce mathematically accurate results
2. Efficiency - The implementation should optimize for both time and memory
3. Readability - Code should be clear and well-documented
4. Extensibility - New gate types and simulation methods should be easy to add