tools-only Hardware Integration
This guide covers running quantum circuits on real quantum hardware through Cirq's device interfaces and service providers.
Device Representation
Device Classes
import cirq
# Define device with connectivity
class MyDevice(cirq.Device):
def __init__(self, qubits, connectivity):
self.qubits = qubits
self.connectivity = connectivity
@property
def metadata(self):
return cirq.DeviceMetadata(
self.qubits,
self.connectivity
)
def validate_operation(self, operation):
# Check if operation is valid on this device
if len(operation.qubits) == 2:
q0, q1 = operation.qubits
if (q0, q1) not in self.connectivity:
raise ValueError(f"Qubits {q0} and {q1} not connected")
Device Constraints
# Check device metadata
device = cirq_google.Sycamore
# Get qubit topology
qubits = device.metadata.qubit_set
print(f"Available qubits: {len(qubits)}")
# Check connectivity
for q0 in qubits:
neighbors = device.metadata.nx_graph.neighbors(q0)
print(f"{q0} connected to: {list(neighbors)}")
# Validate circuit against device
try:
device.validate_circuit(circuit)
print("Circuit is valid for device")
except ValueError as e:
print(f"Invalid circuit: {e}")
Qubit Selection
Best Qubit Selection
import cirq_google
# Get calibration metrics
processor = cirq_google.get_engine().get_processor('weber')
calibration = processor.get_current_calibration()
# Find qubits with lowest error rates
def select_best_qubits(calibration, n_qubits):
"""Select n qubits with best single-qubit gate fidelity."""
qubit_fidelities = {}
for qubit in calibration.keys():
if 'single_qubit_rb_average_error_per_gate' in calibration[qubit]:
error = calibration[qubit]['single_qubit_rb_average_error_per_gate']
qubit_fidelities[qubit] = 1 - error
# Sort by fidelity
best_qubits = sorted(
qubit_fidelities.items(),
key=lambda x: x[1],
reverse=True
)[:n_qubits]
return [q for q, _ in best_qubits]
best_qubits = select_best_qubits(calibration, n_qubits=10)
Topology-Aware Selection
def select_connected_qubits(device, n_qubits):
"""Select connected qubits forming a path or grid."""
graph = device.metadata.nx_graph
# Find connected subgraph
import networkx as nx
for node in graph.nodes():
subgraph = nx.ego_graph(graph, node, radius=n_qubits)
if len(subgraph) >= n_qubits:
return list(subgraph.nodes())[:n_qubits]
raise ValueError(f"Could not find {n_qubits} connected qubits")
Service Providers
Google Quantum AI (Cirq-Google)
Setup
import cirq_google
# Authenticate (requires Google Cloud project)
# Set environment variable: GOOGLE_CLOUD_PROJECT=your-project-id
# Get quantum engine
engine = cirq_google.get_engine()
# List available processors
processors = engine.list_processors()
for processor in processors:
print(f"Processor: {processor.processor_id}")
Running on Google Hardware
# Create circuit for Google device
import cirq_google
# Get processor
processor = engine.get_processor('weber')
device = processor.get_device()
# Create circuit on device qubits
qubits = sorted(device.metadata.qubit_set)[:5]
circuit = cirq.Circuit(
cirq.H(qubits[0]),
cirq.CZ(qubits[0], qubits[1]),
cirq.measure(*qubits, key='result')
)
# Validate and run
device.validate_circuit(circuit)
job = processor.run(circuit, repetitions=1000)
# Get results
results = job.results()[0]
print(results.histogram(key='result'))
IonQ
Setup
import cirq_ionq
# Set API key
# Option 1: Environment variable
# export IONQ_API_KEY=your_api_key
# Option 2: In code
service = cirq_ionq.Service(api_key='your_api_key')
Running on IonQ
import cirq_ionq
# Create service
service = cirq_ionq.Service(api_key='your_api_key')
# Create circuit (IonQ uses generic qubits)
qubits = cirq.LineQubit.range(3)
circuit = cirq.Circuit(
cirq.H(qubits[0]),
cirq.CNOT(qubits[0], qubits[1]),
cirq.CNOT(qubits[1], qubits[2]),
cirq.measure(*qubits, key='result')
)
# Run on simulator
result = service.run(
circuit=circuit,
repetitions=1000,
target='simulator'
)
print(result.histogram(key='result'))
# Run on hardware
result = service.run(
circuit=circuit,
repetitions=1000,
target='qpu'
)
IonQ Job Management
# Create job
job = service.create_job(circuit, repetitions=1000, target='qpu')
# Check job status
status = job.status()
print(f"Job status: {status}")
# Wait for completion
job.wait_until_complete()
# Get results
results = job.results()
IonQ Calibration Data
# Get current calibration
calibration = service.get_current_calibration()
# Access metrics
print(f"Fidelity: {calibration['fidelity']}")
print(f"Timing: {calibration['timing']}")
Azure Quantum
Setup
from azure.quantum import Workspace
from azure.quantum.cirq import AzureQuantumService
# Create workspace connection
workspace = Workspace(
resource_id="/subscriptions/.../resourceGroups/.../providers/Microsoft.Quantum/Workspaces/...",
location="eastus"
)
# Create Cirq service
service = AzureQuantumService(workspace)
Running on Azure Quantum (IonQ Backend)
# List available targets
targets = service.targets()
for target in targets:
print(f"Target: {target.name}")
# Run on IonQ simulator
result = service.run(
circuit=circuit,
repetitions=1000,
target='ionq.simulator'
)
# Run on IonQ QPU
result = service.run(
circuit=circuit,
repetitions=1000,
target='ionq.qpu'
)
Running on Azure Quantum (Honeywell Backend)
# Run on Honeywell System Model H1
result = service.run(
circuit=circuit,
repetitions=1000,
target='honeywell.hqs-lt-s1'
)
# Check Honeywell-specific options
target_info = service.get_target('honeywell.hqs-lt-s1')
print(f"Target info: {target_info}")
AQT (Alpine Quantum Technologies)
Setup
import cirq_aqt
# Set API token
# export AQT_TOKEN=your_token
# Create service
service = cirq_aqt.AQTSampler(
remote_host='https://gateway.aqt.eu',
access_token='your_token'
)
Running on AQT
# Create circuit
qubits = cirq.LineQubit.range(3)
circuit = cirq.Circuit(
cirq.H(qubits[0]),
cirq.CNOT(qubits[0], qubits[1]),
cirq.measure(*qubits, key='result')
)
# Run on simulator
result = service.run(
circuit,
repetitions=1000,
target='simulator'
)
# Run on device
result = service.run(
circuit,
repetitions=1000,
target='device'
)
Pasqal
Setup
import cirq_pasqal
# Create Pasqal device
device = cirq_pasqal.PasqalDevice(qubits=cirq.LineQubit.range(10))
Running on Pasqal
# Create sampler
sampler = cirq_pasqal.PasqalSampler(
remote_host='https://api.pasqal.cloud',
access_token='your_token',
device=device
)
# Run circuit
result = sampler.run(circuit, repetitions=1000)
Hardware Best Practices
Circuit Optimization for Hardware
def optimize_for_hardware(circuit, device):
"""Optimize circuit for specific hardware."""
from cirq.transformers import (
optimize_for_target_gateset,
merge_single_qubit_gates_to_phxz,
drop_negligible_operations
)
# Get device gateset
if hasattr(device, 'gateset'):
gateset = device.gateset
else:
gateset = cirq.CZTargetGateset() # Default
# Optimize
circuit = merge_single_qubit_gates_to_phxz(circuit)
circuit = drop_negligible_operations(circuit)
circuit = optimize_for_target_gateset(circuit, gateset=gateset)
return circuit
Error Mitigation
def run_with_readout_error_mitigation(circuit, sampler, repetitions):
"""Mitigate readout errors using calibration."""
# Measure readout error
cal_circuits = []
for state in range(2**len(circuit.qubits)):
cal_circuit = cirq.Circuit()
for i, q in enumerate(circuit.qubits):
if state & (1 << i):
cal_circuit.append(cirq.X(q))
cal_circuit.append(cirq.measure(*circuit.qubits, key='m'))
cal_circuits.append(cal_circuit)
# Run calibration
cal_results = [sampler.run(c, repetitions=1000) for c in cal_circuits]
# Build confusion matrix
# ... (implementation details)
# Run actual circuit
result = sampler.run(circuit, repetitions=repetitions)
# Apply correction
# ... (apply inverse of confusion matrix)
return result
Job Management
def submit_jobs_in_batches(circuits, sampler, batch_size=10):
"""Submit multiple circuits in batches."""
jobs = []
for i in range(0, len(circuits), batch_size):
batch = circuits[i:i+batch_size]
job_ids = []
for circuit in batch:
job = sampler.run_async(circuit, repetitions=1000)
job_ids.append(job)
jobs.extend(job_ids)
# Wait for all jobs
results = [job.result() for job in jobs]
return results
Device Specifications
Checking Device Capabilities
def print_device_info(device):
"""Print device capabilities and constraints."""
print(f"Device: {device}")
print(f"Number of qubits: {len(device.metadata.qubit_set)}")
# Gate support
print("\nSupported gates:")
if hasattr(device, 'gateset'):
for gate in device.gateset.gates:
print(f" - {gate}")
# Connectivity
print("\nConnectivity:")
graph = device.metadata.nx_graph
print(f" Edges: {graph.number_of_edges()}")
print(f" Average degree: {sum(dict(graph.degree()).values()) / graph.number_of_nodes():.2f}")
# Duration constraints
if hasattr(device, 'gate_durations'):
print("\nGate durations:")
for gate, duration in device.gate_durations.items():
print(f" {gate}: {duration}")
Authentication and Access
Setting Up Credentials
Google Cloud:
# Install gcloud CLI
# Visit: https://cloud.google.com/sdk/docs/install
# Authenticate
gcloud auth application-default login
# Set project
export GOOGLE_CLOUD_PROJECT=your-project-id
IonQ:
# Set API key
export IONQ_API_KEY=your_api_key
Azure Quantum:
# Use Azure CLI or workspace connection string
# See: https://docs.microsoft.com/azure/quantum/
AQT:
# Request access token from AQT
export AQT_TOKEN=your_token
Pasqal:
# Request API access from Pasqal
export PASQAL_TOKEN=your_token
Best Practices
- Validate circuits before submission: Use device.validate_circuit()
- Optimize for target hardware: Decompose to native gates
- Select best qubits: Use calibration data for qubit selection
- Monitor job status: Check job completion before retrieving results
- Implement error mitigation: Use readout error correction
- Batch jobs efficiently: Submit multiple circuits together
- Respect rate limits: Follow provider-specific API limits
- Store results: Save expensive hardware results immediately
- Test on simulators first: Validate on simulators before hardware
- Keep circuits shallow: Hardware has limited coherence times