Quantum Multiplier

A high-performance quantum circuit simulator specifically designed for multiplication operations using the Cuccaro adder algorithm. This simulator features memory-aware allocation, basis-state tracking for fast measurement, and comprehensive circuit analysis capabilities.

Features

• High-Performance Simulation: Vectorized quantum gate operations for optimal performance
• Memory Management: Early warning system for large state vector allocations
• Basis-State Tracking: O(1) measurement complexity for basis-preserving circuits
• Cuccaro Adder: Efficient quantum addition using MAJ/UMA operations
• Dual Metrics Modes: Fast logical metrics (default) or detailed decomposition analysis
• Interactive CLI: Command-line tool with demo mode and flexible options
• QASM Export: Generate OpenQASM 2.0 code for quantum hardware deployment
• MCX Decomposition: Offline Barenco decomposition for multi-controlled X gates
• Topology Awareness: Robust circuit depth estimation with bounds checking
• Error Handling: Clear error messages and input validation

Installation

From Source

git clone https://github.com/scheitelpunk/Quantum_multiplier.git
cd Quantum_multiplier
pip install -e .

Development Installation

git clone https://github.com/scheitelpunk/Quantum_multiplier.git
cd Quantum_multiplier
pip install -e .[dev]

Quick Start

Command Line Interface

# Basic multiplication (fast, logical metrics only)
quantum-multiply 7 8

# Run demonstration with test cases
quantum-multiply --demo

# With detailed decomposition metrics (slower)
quantum-multiply 15 16 --metrics-mode decompose

# Export QASM circuits
quantum-multiply 3 5 --export-qasm

# Custom memory threshold
quantum-multiply 9 9 --warn-memory-gb 4.0

Python API

from quantum_multiplier import QuantumMultiplier

# Initialize the multiplier
qm = QuantumMultiplier(max_qubits=64, warn_memory_gb=8.0)

# Perform multiplication (default: fast logical metrics)
result = qm.multiply(7, 8)  # or metrics_mode="logical" 

# For detailed physical circuit analysis (slower)
# result = qm.multiply(7, 8, metrics_mode="decompose")

print(f"Result: {result['quantum_result']}")
print(f"Execution time: {result['execution_time_ms']:.3f}ms")
print(f"Physical qubits required: {result['physical_qubits']}")

Algorithm Overview

The quantum multiplier implements the shift-and-add multiplication algorithm using:

1. Cuccaro Adder: An efficient reversible adder using MAJ (majority) and UMA (unmajority) operations
2. Controlled Operations: Each addition is controlled by bits of the second multiplicand
3. Clean Initialization: State preparation using only X gates (no direct state vector manipulation)
4. Basis Tracking: Computational basis state tracking for fast measurement without state vector scanning

Circuit Structure

For multiplying n-bit numbers A and B:

• Input registers: A (n qubits), B (n qubits)
• Result register: 2n qubits to store A×B
• Auxiliary qubits: 1 carry qubit + virtual ancillas for MCX decomposition

Performance Characteristics

Time Complexity

• Gate operations: O(n²) where n is the bit width
• Memory allocation: O(2^(2n+1)) for the state vector
• Measurement: O(1) due to basis-state tracking

Space Complexity

• Logical qubits: 2n + 1 (for n-bit multiplication)
• Physical qubits: Depends on MCX decomposition (typically 2n + 1 + O(n) ancillas for Barenco decomposition)

API Reference

QuantumMultiplier

Main class for performing quantum multiplication.

class QuantumMultiplier:
    def __init__(self, max_qubits: int = 64, topology: Optional[Topology] = None, warn_memory_gb: float = 8.0)
    
    def multiply(self, a: int, b: int, metrics_mode: str = "decompose") -> Dict[str, Any]

Parameters:

• max_qubits: Maximum number of qubits allowed
• topology: Hardware topology for depth estimation (optional)
• warn_memory_gb: Memory threshold for allocation warnings

Returns:

• quantum_result: The computed product
• classical_result: Classical verification
• n_qubits: Number of logical qubits used
• physical_qubits: Number of physical qubits (including ancillas)
• execution_time_ms: Runtime in milliseconds
• metrics: Detailed circuit metrics
• export: QASM circuit representations

QuantumSimulator

Low-level quantum circuit simulator.

class QuantumSimulator:
    def X(self, t: int)  # Pauli-X gate
    def CX(self, c: int, t: int)  # Controlled-X gate
    def CCX(self, a: int, b: int, t: int)  # Toffoli gate
    def MCX(self, ctrls: List[int], tgt: int)  # Multi-controlled X
    def SWAP(self, u: int, v: int)  # Swap gate

Topology Support

Define custom hardware topologies for realistic depth estimation:

from quantum_multiplier import Topology

# Linear topology
linear = Topology(n_qubits=10, edges=[(i, i+1) for i in range(9)])

# Grid topology
grid = Topology(n_qubits=16, edges=[...])  # Define 4x4 grid connections

qm = QuantumMultiplier(topology=grid)

Examples

Basic Usage

from quantum_multiplier import QuantumMultiplier

qm = QuantumMultiplier()

# Multiply two positive integers
result = qm.multiply(12, 15)
print(f"12 × 15 = {result['quantum_result']}")

# Handle negative numbers
result = qm.multiply(-7, 8)
print(f"-7 × 8 = {result['quantum_result']}")

CLI Examples

# Quick demonstration
quantum-multiply --demo

# Basic usage (fast)
quantum-multiply 7 8

# With all options
quantum-multiply 7 8 \
  --metrics-mode decompose \
  --max-qubits 128 \
  --warn-memory-gb 16.0 \
  --export-qasm

# Get help
quantum-multiply --help

Circuit Analysis

# Fast analysis (default)
result = qm.multiply(7, 8)  # uses metrics_mode="logical"

# Detailed analysis (slower)
result = qm.multiply(7, 8, metrics_mode="decompose")

# Logical circuit metrics
logical = result["metrics"]["logical"]
print(f"Logical gates: {logical['gate_counts']}")
print(f"Circuit depth: {logical['depth']}")

# Physical circuit metrics (after MCX decomposition)
physical = result["metrics"]["decomposed"]
print(f"Physical gates: {physical['gate_counts']}")
print(f"Peak ancilla usage: {physical['peak_virtual_ancillas']}")

QASM Export

result = qm.multiply(3, 5)

# Export logical circuit
with open("multiply_3x5.qasm", "w") as f:
    f.write(result["export"]["qasm_logical"])

# Export decomposed circuit (if available)
if result["export"]["qasm_decomposed"]:
    with open("multiply_3x5_physical.qasm", "w") as f:
        f.write(result["export"]["qasm_decomposed"])

Testing

Run the test suite:

pytest

With coverage:

pytest --cov=quantum_multiplier --cov-report=html

Performance Tips

1. Memory Management: Monitor the memory warning threshold for large multiplications
2. Metrics Mode: Use metrics_mode="logical" (default) for faster execution when physical metrics aren't needed
3. Demo Mode: Use quantum-multiply --demo for quick testing without specifying numbers
4. Topology: Provide realistic topology information for accurate depth estimation, or None for faster execution
5. Bit Width: Consider the exponential scaling - 20+ bit multiplications require significant memory
6. Error Handling: The simulator provides clear ValueError messages instead of cryptic assertions

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

pip install -e .[dev]
pre-commit install

Code Style

This project uses:

• Black for code formatting
• isort for import sorting
• flake8 for linting
• mypy for type checking

Run all checks:

black quantum_multiplier tests
isort quantum_multiplier tests
flake8 quantum_multiplier tests
mypy quantum_multiplier

License

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

Citation

If you use this software in your research, please cite:

@software{quantum_multiplier,
  title={Quantum Multiplier: High-Performance Quantum Circuit Simulation for Multiplication},
  author={Michael Neuberger},
  organization={Versino PsiOmega GmbH},
  year={2025},
  url={https://github.com/scheitelpunk/Quantum_multiplier}
}

Acknowledgments

• Based on the Cuccaro adder algorithm for efficient quantum addition
• Implements Barenco et al. decomposition for multi-controlled gates
• Inspired by various quantum computing frameworks and simulators

Roadmap

• GPU acceleration support
• Distributed simulation capabilities
• Additional arithmetic operations (division, modular arithmetic)
• Noise model support
• Quantum hardware backend integration
• Graphical circuit visualization