@synsci/cli-darwin-x64-baseline 1.1.77 → 1.1.78

package/bin/skills/qiskit/references/primitives.md

@@ -0,0 +1,277 @@
+# Qiskit Primitives
+
+Primitives are the fundamental building blocks for executing quantum circuits. Qiskit provides two main primitives: **Sampler** (for measuring bitstrings) and **Estimator** (for computing expectation values).
+
+## Primitive Types
+
+### Sampler
+Calculates probabilities or quasi-probabilities of bitstrings from quantum circuits. Use when you need:
+- Measurement outcomes
+- Output probability distributions
+- Sampling from quantum states
+
+### Estimator
+Computes expectation values of observables for quantum circuits. Use when you need:
+- Energy calculations
+- Observable measurements
+- Variational algorithm optimization
+
+## V2 Interface (Current Standard)
+
+Qiskit uses V2 primitives (BaseSamplerV2, BaseEstimatorV2) as the current standard. V1 primitives are legacy.
+
+## Sampler Primitive
+
+### StatevectorSampler (Local Simulation)
+
+```python
+from qiskit import QuantumCircuit
+from qiskit.primitives import StatevectorSampler
+
+# Create circuit
+qc = QuantumCircuit(2)
+qc.h(0)
+qc.cx(0, 1)
+qc.measure_all()
+
+# Run with Sampler
+sampler = StatevectorSampler()
+result = sampler.run([qc], shots=1024).result()
+
+# Access results
+counts = result[0].data.meas.get_counts()
+print(counts)  # e.g., {'00': 523, '11': 501}
+```
+
+### Multiple Circuits
+
+```python
+qc1 = QuantumCircuit(2)
+qc1.h(0)
+qc1.measure_all()
+
+qc2 = QuantumCircuit(2)
+qc2.x(0)
+qc2.measure_all()
+
+# Run multiple circuits
+sampler = StatevectorSampler()
+job = sampler.run([qc1, qc2], shots=1000)
+results = job.result()
+
+# Access individual results
+counts1 = results[0].data.meas.get_counts()
+counts2 = results[1].data.meas.get_counts()
+```
+
+### Using Parameters
+
+```python
+from qiskit.circuit import Parameter
+
+theta = Parameter('θ')
+qc = QuantumCircuit(1)
+qc.ry(theta, 0)
+qc.measure_all()
+
+# Run with parameter values
+sampler = StatevectorSampler()
+param_values = [[0], [np.pi/4], [np.pi/2]]
+result = sampler.run([(qc, param_values)], shots=1024).result()
+```
+
+## Estimator Primitive
+
+### StatevectorEstimator (Local Simulation)
+
+```python
+from qiskit import QuantumCircuit
+from qiskit.primitives import StatevectorEstimator
+from qiskit.quantum_info import SparsePauliOp
+
+# Create circuit WITHOUT measurements
+qc = QuantumCircuit(2)
+qc.h(0)
+qc.cx(0, 1)
+
+# Define observable
+observable = SparsePauliOp(["ZZ", "XX"])
+
+# Run Estimator
+estimator = StatevectorEstimator()
+result = estimator.run([(qc, observable)]).result()
+
+# Access expectation values
+exp_value = result[0].data.evs
+print(f"Expectation value: {exp_value}")
+```
+
+### Multiple Observables
+
+```python
+from qiskit.quantum_info import SparsePauliOp
+
+qc = QuantumCircuit(2)
+qc.h(0)
+
+obs1 = SparsePauliOp(["ZZ"])
+obs2 = SparsePauliOp(["XX"])
+
+estimator = StatevectorEstimator()
+result = estimator.run([(qc, obs1), (qc, obs2)]).result()
+
+ev1 = result[0].data.evs
+ev2 = result[1].data.evs
+```
+
+### Parameterized Estimator
+
+```python
+from qiskit.circuit import Parameter
+import numpy as np
+
+theta = Parameter('θ')
+qc = QuantumCircuit(1)
+qc.ry(theta, 0)
+
+observable = SparsePauliOp(["Z"])
+
+# Run with multiple parameter values
+estimator = StatevectorEstimator()
+param_values = [[0], [np.pi/4], [np.pi/2], [np.pi]]
+result = estimator.run([(qc, observable, param_values)]).result()
+```
+
+## IBM Quantum Runtime Primitives
+
+For running on real hardware, use runtime primitives:
+
+### Runtime Sampler
+
+```python
+from qiskit_ibm_runtime import QiskitRuntimeService, SamplerV2 as Sampler
+
+service = QiskitRuntimeService()
+backend = service.backend("ibm_brisbane")
+
+qc = QuantumCircuit(2)
+qc.h(0)
+qc.cx(0, 1)
+qc.measure_all()
+
+# Run on real hardware
+sampler = Sampler(backend)
+job = sampler.run([qc], shots=1024)
+result = job.result()
+counts = result[0].data.meas.get_counts()
+```
+
+### Runtime Estimator
+
+```python
+from qiskit_ibm_runtime import QiskitRuntimeService, EstimatorV2 as Estimator
+from qiskit.quantum_info import SparsePauliOp
+
+service = QiskitRuntimeService()
+backend = service.backend("ibm_brisbane")
+
+qc = QuantumCircuit(2)
+qc.h(0)
+qc.cx(0, 1)
+
+observable = SparsePauliOp(["ZZ"])
+
+# Run on real hardware
+estimator = Estimator(backend)
+job = estimator.run([(qc, observable)])
+result = job.result()
+exp_value = result[0].data.evs
+```
+
+## Sessions for Iterative Workloads
+
+Sessions group multiple jobs to reduce queue wait times:
+
+```python
+from qiskit_ibm_runtime import Session
+
+service = QiskitRuntimeService()
+backend = service.backend("ibm_brisbane")
+
+with Session(backend=backend) as session:
+    sampler = Sampler(session=session)
+
+    # Run multiple jobs in session
+    job1 = sampler.run([qc1], shots=1024)
+    result1 = job1.result()
+
+    job2 = sampler.run([qc2], shots=1024)
+    result2 = job2.result()
+```
+
+## Batch Mode for Parallel Jobs
+
+Batch mode runs independent jobs in parallel:
+
+```python
+from qiskit_ibm_runtime import Batch
+
+service = QiskitRuntimeService()
+backend = service.backend("ibm_brisbane")
+
+with Batch(backend=backend) as batch:
+    sampler = Sampler(session=batch)
+
+    # Submit multiple independent jobs
+    job1 = sampler.run([qc1], shots=1024)
+    job2 = sampler.run([qc2], shots=1024)
+
+    # Retrieve results when ready
+    result1 = job1.result()
+    result2 = job2.result()
+```
+
+## Result Processing
+
+### Sampler Results
+
+```python
+result = sampler.run([qc], shots=1024).result()
+
+# Get counts
+counts = result[0].data.meas.get_counts()
+
+# Get probabilities
+probs = {k: v/1024 for k, v in counts.items()}
+
+# Get metadata
+metadata = result[0].metadata
+```
+
+### Estimator Results
+
+```python
+result = estimator.run([(qc, observable)]).result()
+
+# Expectation value
+exp_val = result[0].data.evs
+
+# Standard deviation (if available)
+std_dev = result[0].data.stds
+
+# Metadata
+metadata = result[0].metadata
+```
+
+## Differences from V1 Primitives
+
+**V2 Improvements:**
+- More flexible parameter binding
+- Better result structure
+- Improved performance
+- Cleaner API design
+
+**Migration from V1:**
+- Use `StatevectorSampler` instead of `Sampler`
+- Use `StatevectorEstimator` instead of `Estimator`
+- Result access changed from `.result().quasi_dists[0]` to `.result()[0].data.meas.get_counts()`

package/bin/skills/qiskit/references/setup.md

@@ -0,0 +1,99 @@
+# Qiskit Setup and Installation
+
+## Installation
+
+Install Qiskit using uv:
+
+```bash
+uv pip install qiskit
+```
+
+For visualization capabilities:
+
+```bash
+uv pip install "qiskit[visualization]" matplotlib
+```
+
+## Python Environment Setup
+
+Create and activate a virtual environment to isolate dependencies:
+
+```bash
+# macOS/Linux
+python3 -m venv .venv
+source .venv/bin/activate
+
+# Windows
+python -m venv .venv
+.venv\Scripts\activate
+```
+
+## Supported Python Versions
+
+Check the [Qiskit PyPI page](https://pypi.org/project/qiskit/) for currently supported Python versions. As of 2025, Qiskit typically supports Python 3.8+.
+
+## IBM Quantum Account Setup
+
+To run circuits on real IBM Quantum hardware, you need an IBM Quantum account and API token.
+
+### Creating an Account
+
+1. Visit [IBM Quantum Platform](https://quantum.ibm.com/)
+2. Sign up for a free account
+3. Navigate to your account settings to retrieve your API token
+
+### Configuring Authentication
+
+Save your IBM Quantum credentials:
+
+```python
+from qiskit_ibm_runtime import QiskitRuntimeService
+
+# Save credentials (first time only)
+QiskitRuntimeService.save_account(
+    channel="ibm_quantum",
+    token="YOUR_IBM_QUANTUM_TOKEN"
+)
+
+# Later sessions - load saved credentials
+service = QiskitRuntimeService()
+```
+
+### Environment Variable Method
+
+Alternatively, set the API token as an environment variable:
+
+```bash
+export QISKIT_IBM_TOKEN="YOUR_IBM_QUANTUM_TOKEN"
+```
+
+## Local Development (No Account Required)
+
+You can build and test quantum circuits locally without an IBM Quantum account using simulators:
+
+```python
+from qiskit import QuantumCircuit
+from qiskit.primitives import StatevectorSampler
+
+qc = QuantumCircuit(2)
+qc.h(0)
+qc.cx(0, 1)
+qc.measure_all()
+
+# Run locally with simulator
+sampler = StatevectorSampler()
+result = sampler.run([qc], shots=1024).result()
+```
+
+## Verifying Installation
+
+Test your installation:
+
+```python
+import qiskit
+print(qiskit.__version__)
+
+from qiskit import QuantumCircuit
+qc = QuantumCircuit(2)
+print("Qiskit installed successfully!")
+```

package/bin/skills/qiskit/references/transpilation.md

@@ -0,0 +1,286 @@
+# Circuit Transpilation and Optimization
+
+Transpilation is the process of rewriting a quantum circuit to match the topology and gate set of a specific quantum device, while optimizing for execution on noisy quantum computers.
+
+## Why Transpilation?
+
+**Problem**: Abstract quantum circuits may use gates not available on hardware and assume all-to-all qubit connectivity.
+
+**Solution**: Transpilation transforms circuits to:
+1. Use only hardware-native gates (basis gates)
+2. Respect physical qubit connectivity
+3. Minimize circuit depth and gate count
+4. Optimize for reduced errors on noisy devices
+
+## Basic Transpilation
+
+### Simple Transpile
+
+```python
+from qiskit import QuantumCircuit, transpile
+
+qc = QuantumCircuit(3)
+qc.h(0)
+qc.cx(0, 1)
+qc.cx(1, 2)
+
+# Transpile for a specific backend
+transpiled_qc = transpile(qc, backend=backend)
+```
+
+### Optimization Levels
+
+Choose optimization level 0-3:
+
+```python
+# Level 0: No optimization (fastest)
+qc_0 = transpile(qc, backend=backend, optimization_level=0)
+
+# Level 1: Light optimization
+qc_1 = transpile(qc, backend=backend, optimization_level=1)
+
+# Level 2: Moderate optimization (default)
+qc_2 = transpile(qc, backend=backend, optimization_level=2)
+
+# Level 3: Heavy optimization (slowest, best results)
+qc_3 = transpile(qc, backend=backend, optimization_level=3)
+```
+
+**Qiskit SDK v2.2** provides **83x faster transpilation** compared to competitors.
+
+## Transpilation Stages
+
+The transpiler pipeline consists of six stages:
+
+### 1. Init Stage
+- Validates circuit instructions
+- Translates multi-qubit gates to standard form
+
+### 2. Layout Stage
+- Maps virtual qubits to physical qubits
+- Considers qubit connectivity and error rates
+
+```python
+from qiskit.transpiler import CouplingMap
+
+# Define custom coupling
+coupling = CouplingMap([(0, 1), (1, 2), (2, 3)])
+qc_transpiled = transpile(qc, coupling_map=coupling)
+```
+
+### 3. Routing Stage
+- Inserts SWAP gates to satisfy connectivity constraints
+- Minimizes additional SWAP overhead
+
+### 4. Translation Stage
+- Converts gates to hardware basis gates
+- Typical basis: {RZ, SX, X, CX}
+
+```python
+# Specify basis gates
+basis_gates = ['cx', 'id', 'rz', 'sx', 'x']
+qc_transpiled = transpile(qc, basis_gates=basis_gates)
+```
+
+### 5. Optimization Stage
+- Reduces gate count and circuit depth
+- Applies gate cancellation and commutation rules
+- Uses **virtual permutation elision** (levels 2-3)
+- Finds separable operations to decompose
+
+### 6. Scheduling Stage
+- Adds timing information for pulse-level control
+
+## Advanced Optimization Features
+
+### Virtual Permutation Elision
+
+At optimization levels 2-3, Qiskit analyzes commutation structure to eliminate unnecessary SWAP gates by tracking virtual qubit permutations.
+
+### Gate Cancellation
+
+Identifies and removes pairs of gates that cancel:
+- X-X → I
+- H-H → I
+- CNOT-CNOT → I
+
+### Numerical Decomposition
+
+Splits two-qubit gates that can be expressed as separable one-qubit operations.
+
+## Common Transpilation Parameters
+
+### Initial Layout
+
+Specify which physical qubits to use:
+
+```python
+# Use specific physical qubits
+initial_layout = [0, 2, 4]  # Maps circuit qubits 0,1,2 to physical qubits 0,2,4
+qc_transpiled = transpile(qc, backend=backend, initial_layout=initial_layout)
+```
+
+### Approximation Degree
+
+Trade accuracy for fewer gates (0.0 = max approximation, 1.0 = no approximation):
+
+```python
+# Allow 5% approximation error for fewer gates
+qc_transpiled = transpile(qc, backend=backend, approximation_degree=0.95)
+```
+
+### Seed for Reproducibility
+
+```python
+qc_transpiled = transpile(qc, backend=backend, seed_transpiler=42)
+```
+
+### Scheduling Method
+
+```python
+# Add timing constraints
+qc_transpiled = transpile(
+    qc,
+    backend=backend,
+    scheduling_method='alap'  # As Late As Possible
+)
+```
+
+## Transpiling for Simulators
+
+Even for simulators, transpilation can optimize circuits:
+
+```python
+from qiskit_aer import AerSimulator
+
+simulator = AerSimulator()
+qc_optimized = transpile(qc, backend=simulator, optimization_level=3)
+
+# Compare gate counts
+print(f"Original: {qc.size()} gates")
+print(f"Optimized: {qc_optimized.size()} gates")
+```
+
+## Target-Aware Transpilation
+
+Use `Target` objects for detailed backend specifications:
+
+```python
+from qiskit.transpiler import Target
+
+# Transpile with target specification
+qc_transpiled = transpile(qc, target=backend.target)
+```
+
+## Circuit Analysis After Transpilation
+
+```python
+qc_transpiled = transpile(qc, backend=backend, optimization_level=3)
+
+# Analyze results
+print(f"Depth: {qc_transpiled.depth()}")
+print(f"Gate count: {qc_transpiled.size()}")
+print(f"Operations: {qc_transpiled.count_ops()}")
+
+# Check two-qubit gate count (major error source)
+two_qubit_gates = qc_transpiled.count_ops().get('cx', 0)
+print(f"Two-qubit gates: {two_qubit_gates}")
+```
+
+**Qiskit produces circuits with 29% fewer two-qubit gates** than leading alternatives, significantly reducing errors.
+
+## Multiple Circuit Transpilation
+
+Transpile multiple circuits efficiently:
+
+```python
+circuits = [qc1, qc2, qc3]
+transpiled_circuits = transpile(
+    circuits,
+    backend=backend,
+    optimization_level=3
+)
+```
+
+## Pre-transpilation Best Practices
+
+### 1. Design with Hardware Topology in Mind
+
+Consider backend coupling map when designing circuits:
+
+```python
+# Check backend coupling
+print(backend.coupling_map)
+
+# Design circuits that align with coupling
+```
+
+### 2. Use Native Gates When Possible
+
+Some backends support gates beyond {CX, RZ, SX, X}:
+
+```python
+# Check available basis gates
+print(backend.configuration().basis_gates)
+```
+
+### 3. Minimize Two-Qubit Gates
+
+Two-qubit gates have significantly higher error rates:
+- Design algorithms to minimize CNOT gates
+- Use gate identities to reduce counts
+
+### 4. Test with Simulators First
+
+```python
+from qiskit_aer import AerSimulator
+
+# Test transpilation locally
+sim_backend = AerSimulator.from_backend(backend)
+qc_test = transpile(qc, backend=sim_backend, optimization_level=3)
+```
+
+## Transpilation for Different Providers
+
+### IBM Quantum
+
+```python
+from qiskit_ibm_runtime import QiskitRuntimeService
+
+service = QiskitRuntimeService()
+backend = service.backend("ibm_brisbane")
+qc_transpiled = transpile(qc, backend=backend)
+```
+
+### IonQ
+
+```python
+# IonQ has all-to-all connectivity, different basis gates
+basis_gates = ['gpi', 'gpi2', 'ms']
+qc_transpiled = transpile(qc, basis_gates=basis_gates)
+```
+
+### Amazon Braket
+
+Transpilation depends on specific device (Rigetti, IonQ, etc.)
+
+## Performance Tips
+
+1. **Cache transpiled circuits** - Transpilation is expensive, reuse when possible
+2. **Use appropriate optimization level** - Level 3 is slow but best for production
+3. **Leverage v2.2 speed improvements** - Update to latest Qiskit for 83x speedup
+4. **Parallelize transpilation** - Qiskit automatically parallelizes when transpiling multiple circuits
+
+## Common Issues and Solutions
+
+### Issue: Circuit too deep after transpilation
+**Solution**: Use higher optimization level or redesign circuit with fewer layers
+
+### Issue: Too many SWAP gates inserted
+**Solution**: Adjust initial_layout to better match qubit topology
+
+### Issue: Transpilation takes too long
+**Solution**: Reduce optimization level or update to Qiskit v2.2+ for speed improvements
+
+### Issue: Unexpected gate decompositions
+**Solution**: Check basis_gates and consider specifying custom decomposition rules