qiskit-quantum-algorithms

name	qiskit-quantum-algorithms
metadata	{"category":"Quantum Computing and Quantum AI"}
description	Designing and executing quantum algorithms using IBM Qiskit v1.0+. Use when constructing quantum circuits, variational quantum algorithms (VQE/QAOA), quantum machine learning (QNN), error mitigation (M3/ZNE), transpilation pass managers, or running on IBM Quantum hardware and Aer simulators.
compatibility	Qiskit v1.0+, Python 3.10+, Qiskit Aer, Qiskit IBM Runtime, NumPy, SciPy

Qiskit Quantum Algorithms & Quantum AI Guidelines

This skill details quantum circuit construction, Variational Quantum Eigensolver (VQE) implementation, Quantum Approximate Optimization Algorithm (QAOA), noise mitigation strategies, and Qiskit v1.0+ transpilation workflows.

---

1. Qiskit v1.0+ Architecture & Primitives Paradigm

Qiskit v1.0 introduces a modular architecture centered around Primitives (SamplerV2 and EstimatorV2):

+-------------------------------------------------------------------------+
|                         Quantum Circuit Definition                      |
|           (Qubit Registers, Parametric Gates, Entangled States)         |
+------------------------------------+------------------------------------+
                                     |
                                Transpilation
                                     v
+-------------------------------------------------------------------------+
|                  Target Hardware Transpilation Pass                     |
|           (Coupling Map Alignment, Gate Basis Translation, Routing)     |
+------------------------------------+------------------------------------+
                                     |
                                  Execute
                                     v
+-------------------------------------------------------------------------+
|                        Qiskit Runtime Primitives                        |
|                                                                         |
|     SamplerV2 (Quasi-probability)   |   EstimatorV2 (Expectation Values) |
+-------------------------------------------------------------------------+

1. SamplerV2: Measures individual qubit bitstrings to compute probability distributions.
2. EstimatorV2: Evaluates expectation values of Hermitian operators $\langle \psi | H | \psi \rangle$ directly (used in VQE / QAOA).

---

2. Variational Quantum Eigensolver (VQE) Implementation

Below is a production-grade Qiskit v1.0 implementation of VQE solving for the ground state energy of a molecular Hamiltonian using an efficient parametric ansatz:

import numpy as np
from scipy.optimize import minimize
from qiskit import QuantumCircuit
from qiskit.circuit.library import EfficientSU2
from qiskit.quantum_info import SparsePauliOp
from qiskit_aer.primitives import EstimatorV2 as AerEstimator

class VQEGroundStateSolver:
    def __init__(self, hamiltonian: SparsePauliOp, num_qubits: int):
        self.hamiltonian = hamiltonian
        self.num_qubits = num_qubits
        
        # 1. Construct Parametric Ansatz (Hardware-Efficient SU2)
        self.ansatz = EfficientSU2(
            num_qubits=num_qubits, 
            su2_gates=['ry', 'rz'], 
            entanglement='linear', 
            reps=2
        )
        self.ansatz.measure_all()
        
        # 2. Instantiate Estimator Primitive
        self.estimator = AerEstimator()

    def _cost_function(self, params: np.ndarray) -> float:
        """Evaluates expectation value <psi(params)|H|psi(params)>."""
        # Bind classical parameters to ansatz circuit
        pub = (self.ansatz, self.hamiltonian, params)
        job = self.estimator.run([pub])
        result = job.result()
        
        # Extract expectation value from primitive result array
        expectation_value = result[].data.evs
         (expectation_value)

     () -> :
        
        initial_params = np.random.uniform(-np.pi, np.pi, .ansatz.num_parameters)
        
        
        opt_result = minimize(
            ._cost_function, 
            initial_params, 
            method=, 
            options={: , : }
        )
        
         {
            : opt_result.fun,
            : opt_result.x,
            : opt_result.nfev,
            :   opt_result.success  
        }

 __name__ == :
    
    hamiltonian = SparsePauliOp.from_list([
        (, ),
        (, ),
        (, -)
    ])
    
    solver = VQEGroundStateSolver(hamiltonian, num_qubits=)
    solution = solver.solve()
    (, solution[])

---

3. Qiskit Transpilation & Error Mitigation

3.1 Custom Pass Manager Transpilation

Targeting physical quantum hardware requires transpiling high-level circuits to native hardware gate sets (cz, sx, rz) while optimizing circuit depth:

from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager
from qiskit_ibm_runtime import QiskitRuntimeService

def transpile_for_ibm_backend(circuit: QuantumCircuit, backend_name: str = "ibm_brisbane"):
    # 1. Fetch real hardware target profile
    service = QiskitRuntimeService()
    backend = service.backend(backend_name)
    
    # 2. Generate Preset Pass Manager at Optimization Level 3
    pm = generate_preset_pass_manager(optimization_level=3, target=backend.target)
    
    # 3. Transpile Circuit
    transpiled_circuit = pm.run(circuit)
    
    print(f"Original Depth: {circuit.depth()} -> Transpiled Depth: {transpiled_circuit.depth()}")
    return transpiled_circuit

---

4. Anti-Patterns & Critical Pitfalls

Anti-Pattern	Severity	Consequence	Correct Pattern
Using deprecated Qiskit 0.x methods (execute(), Backend.run())	Critical	API breakage in Qiskit 1.0+	Upgrade code to Qiskit 1.0 SamplerV2 / EstimatorV2 primitives
Un-transpiled execution on physical hardware	Critical	Execution error (Unsupported Gate Set)	Always run through generate_preset_pass_manager targeting backend
Unbounded ansatz depth on NISQ hardware	High	Decoherence & noise drown out quantum signal	Use shallow hardware-efficient ansätze (EfficientSU2 reps <= 3)
Hardcoded measurement mapping	Medium	Faulty bitstring interpretation	Explicitly track classical register bits when sampling
Missing error mitigation on noisy backend	High	Inaccurate expectation values	Enable Zero-Noise Extrapolation (ZNE) or Readout Mitigation

---

5. Verification & Testing Checklist

• Statevector Simulator Verification: Compare VQE results against exact Statevector diagonalization before executing on hardware.
• Circuit Gate Count: Verify 2-qubit gate count (CZ/CNOT) is minimized during pass manager transpilation.
• Qiskit Version Lock: Enforce qiskit>=1.0.0 in requirements.txt.