Azure Quantum Integration

Execute quantum circuits on real quantum hardware through Azure Quantum.

Overview

SoftQCOS provides seamless access to Azure Quantum hardware providers:

Provider	Technology	Qubits	Best For
IonQ	Trapped Ion	29	High fidelity, all-to-all connectivity
Quantinuum	Trapped Ion	56	Highest fidelity, error correction
Rigetti	Superconducting	79	Speed, larger circuits
PASQAL	Neutral Atom	100	Analog quantum simulation

Prerequisites

# Install SDK with Azure support
pip install softqcos-sdk[azure]

You'll need:

• SoftQCOS API key with Azure Quantum access
• (Optional) Azure subscription for dedicated credits

Quick Start

"""Quick start with Azure Quantum through SoftQCOS."""

from softqcos_sdk import QCOSClient

client = QCOSClient()

# Simple circuit
circuit = """
OPENQASM 2.0;
include "qelib1.inc";
qreg q[2];
creg c[2];
h q[0];
cx q[0], q[1];
measure q -> c;
"""

# List available backends
providers = client.azure_quantum.list_providers()
for p in providers:
    print(f"{p.name}: {p.num_qubits} qubits, available={p.available}")

# Estimate cost before execution
estimate = client.azure_quantum.estimate_cost(
    circuit=circuit,
    target="ionq.simulator",
    shots=1024
)
print(f"Estimated cost: €{estimate.cost_eur:.4f}")

# Execute on IonQ simulator (free)
result = client.azure_quantum.execute(
    circuit=circuit,
    target="ionq.simulator",
    shots=1024
)
print(f"Result: {result.counts}")

Available Targets

IonQ

"""IonQ targets through Azure Quantum."""

# Simulator (free, instant)
result = client.azure_quantum.execute(
    circuit=circuit,
    target="ionq.simulator",
    shots=1024
)

# QPU - Aria (paid, queue time)
result = client.azure_quantum.execute(
    circuit=circuit,
    target="ionq.aria-1",
    shots=100  # Use fewer shots for QPU
)

# QPU - Forte (newest, highest performance)
result = client.azure_quantum.execute(
    circuit=circuit,
    target="ionq.forte-1",
    shots=100
)

Quantinuum

"""Quantinuum targets - highest fidelity."""

# Emulator (uses HQC credits)
result = client.azure_quantum.execute(
    circuit=circuit,
    target="quantinuum.sim.h1-1e",
    shots=100
)

# QPU - H1-1 (highest fidelity available)
result = client.azure_quantum.execute(
    circuit=circuit,
    target="quantinuum.qpu.h1-1",
    shots=100
)

# Syntax checker (free, validates circuit)
result = client.azure_quantum.execute(
    circuit=circuit,
    target="quantinuum.sim.h1-1sc",
    shots=1
)

Rigetti

"""Rigetti targets - superconducting."""

# Simulator
result = client.azure_quantum.execute(
    circuit=circuit,
    target="rigetti.sim.qvm",
    shots=1024
)

# QPU - Ankaa-2
result = client.azure_quantum.execute(
    circuit=circuit,
    target="rigetti.qpu.ankaa-2",
    shots=100
)

Cost Estimation

Always estimate costs before executing on real hardware!

"""Comprehensive cost estimation."""

from softqcos_sdk import QCOSClient

client = QCOSClient()

circuit = """
OPENQASM 2.0;
include "qelib1.inc";
qreg q[5];
creg c[5];
h q[0];
cx q[0], q[1];
cx q[1], q[2];
cx q[2], q[3];
cx q[3], q[4];
measure q -> c;
"""

# Compare costs across providers
targets = [
    "ionq.simulator",
    "ionq.aria-1",
    "quantinuum.sim.h1-1e",
    "quantinuum.qpu.h1-1",
    "rigetti.sim.qvm",
    "rigetti.qpu.ankaa-2",
]

print("Cost Comparison for 5-qubit GHZ (100 shots)")
print("=" * 60)
print(f"{'Target':<30} {'Cost (EUR)':<12} {'Time':<15}")
print("-" * 60)

for target in targets:
    try:
        estimate = client.azure_quantum.estimate_cost(
            circuit=circuit,
            target=target,
            shots=100
        )
        print(f"{target:<30} €{estimate.cost_eur:<11.4f} {estimate.time_estimate}")
    except Exception as e:
        print(f"{target:<30} {'N/A':<12} {str(e)[:20]}")

Example Output

Cost Comparison for 5-qubit GHZ (100 shots)
============================================================
Target                         Cost (EUR)   Time
------------------------------------------------------------
ionq.simulator                 €0.0000      instant
ionq.aria-1                    €2.5000      5-15 min
quantinuum.sim.h1-1e           €0.5000      1-5 min
quantinuum.qpu.h1-1            €45.0000     30-60 min
rigetti.sim.qvm                €0.0000      instant
rigetti.qpu.ankaa-2            €1.2000      5-30 min

Production Workflow

"""Production workflow with cost controls and error handling."""

from softqcos_sdk import QCOSClient, AzureQuantumError, QuotaExceededError
import time

def execute_with_budget_control(
    circuit: str,
    target: str,
    shots: int,
    max_cost_eur: float = 10.0,
    max_wait_minutes: int = 30
):
    """Execute on Azure Quantum with budget and time controls."""

    client = QCOSClient()

    # Step 1: Estimate cost
    print(f"📊 Estimating cost for {target}...")
    estimate = client.azure_quantum.estimate_cost(
        circuit=circuit,
        target=target,
        shots=shots
    )

    print(f"   Estimated cost: €{estimate.cost_eur:.4f}")
    print(f"   Estimated time: {estimate.time_estimate}")

    # Step 2: Budget check
    if estimate.cost_eur > max_cost_eur:
        raise ValueError(
            f"Cost €{estimate.cost_eur:.2f} exceeds budget €{max_cost_eur:.2f}"
        )

    # Step 3: Submit job
    print(f"\n⏳ Submitting job to {target}...")
    job = client.azure_quantum.submit(
        circuit=circuit,
        target=target,
        shots=shots
    )

    print(f"   Job ID: {job.job_id}")
    print(f"   Status: {job.status}")

    # Step 4: Wait for completion with timeout
    start_time = time.time()
    timeout_seconds = max_wait_minutes * 60

    while job.status not in ["completed", "failed", "cancelled"]:
        elapsed = time.time() - start_time

        if elapsed > timeout_seconds:
            print(f"\n⚠️  Timeout after {max_wait_minutes} minutes")
            print(f"   Job is still {job.status}")
            print(f"   Check later with: client.azure_quantum.get_job('{job.job_id}')")
            return job

        time.sleep(10)
        job = client.azure_quantum.get_job(job.job_id)
        print(f"   Status: {job.status} ({int(elapsed)}s elapsed)")

    # Step 5: Get results
    if job.status == "completed":
        print(f"\n✅ Job completed!")
        result = client.azure_quantum.get_result(job.job_id)
        print(f"   Counts: {result.counts}")
        return result
    else:
        print(f"\n❌ Job {job.status}")
        if job.error_message:
            print(f"   Error: {job.error_message}")
        return job


# Usage
circuit = """
OPENQASM 2.0;
include "qelib1.inc";
qreg q[2];
creg c[2];
h q[0];
cx q[0], q[1];
measure q -> c;
"""

try:
    result = execute_with_budget_control(
        circuit=circuit,
        target="ionq.aria-1",
        shots=100,
        max_cost_eur=5.0,
        max_wait_minutes=20
    )
except ValueError as e:
    print(f"Budget exceeded: {e}")
except QuotaExceededError as e:
    print(f"Quota exceeded: {e}")
except AzureQuantumError as e:
    print(f"Azure Quantum error: {e}")

Batch Execution

"""Execute multiple circuits efficiently on Azure Quantum."""

from softqcos_sdk import QCOSClient
from concurrent.futures import ThreadPoolExecutor, as_completed

def batch_execute_azure(circuits: list[str], target: str, shots: int = 100):
    """Submit multiple circuits as a batch."""

    client = QCOSClient()

    # Estimate total cost
    total_cost = 0
    for circuit in circuits:
        estimate = client.azure_quantum.estimate_cost(
            circuit=circuit,
            target=target,
            shots=shots
        )
        total_cost += estimate.cost_eur

    print(f"📊 Batch of {len(circuits)} circuits")
    print(f"   Target: {target}")
    print(f"   Total estimated cost: €{total_cost:.2f}")

    confirm = input("Proceed? (y/n): ")
    if confirm.lower() != 'y':
        print("Cancelled")
        return None

    # Submit all jobs
    jobs = []
    for i, circuit in enumerate(circuits):
        job = client.azure_quantum.submit(
            circuit=circuit,
            target=target,
            shots=shots
        )
        jobs.append(job)
        print(f"   Submitted {i+1}/{len(circuits)}: {job.job_id}")

    # Wait for all to complete
    print("\n⏳ Waiting for jobs to complete...")

    results = []
    for job in jobs:
        while job.status not in ["completed", "failed", "cancelled"]:
            time.sleep(5)
            job = client.azure_quantum.get_job(job.job_id)

        if job.status == "completed":
            result = client.azure_quantum.get_result(job.job_id)
            results.append(result)
        else:
            results.append(None)

    completed = sum(1 for r in results if r is not None)
    print(f"\n✅ Completed: {completed}/{len(circuits)}")

    return results

Circuit Optimization for Hardware

"""Optimize circuits for specific Azure Quantum targets."""

from softqcos_sdk import QCOSClient

client = QCOSClient()

# Your circuit
circuit = """
OPENQASM 2.0;
include "qelib1.inc";
qreg q[4];
creg c[4];
h q[0];
cx q[0], q[1];
cx q[1], q[2];
cx q[2], q[3];
measure q -> c;
"""

# Optimize for IonQ (native gates: GPI, GPI2, MS)
optimized_ionq = client.optimize(
    circuit=circuit,
    target="ionq",
    objective="max_fidelity"
)
print(f"IonQ optimized: {optimized_ionq.improvements}")

# Optimize for Quantinuum (native gates: RZ, RZZ, RXX)
optimized_quantinuum = client.optimize(
    circuit=circuit,
    target="quantinuum",
    objective="max_fidelity"
)
print(f"Quantinuum optimized: {optimized_quantinuum.improvements}")

# Optimize for Rigetti (native gates: RX, RZ, CZ)
optimized_rigetti = client.optimize(
    circuit=circuit,
    target="rigetti",
    objective="min_depth"  # Minimize depth for superconducting
)
print(f"Rigetti optimized: {optimized_rigetti.improvements}")

# Execute with optimized circuit
result = client.azure_quantum.execute(
    circuit=optimized_ionq.optimized_qasm,
    target="ionq.aria-1",
    shots=100
)

Error Handling

"""Handle Azure Quantum specific errors."""

from softqcos_sdk import (
    QCOSClient,
    AzureQuantumError,
    ProviderUnavailableError,
    QuotaExceededError,
    CircuitValidationError,
)

client = QCOSClient()

try:
    result = client.azure_quantum.execute(
        circuit=circuit,
        target="ionq.aria-1",
        shots=100
    )
except CircuitValidationError as e:
    print(f"❌ Circuit invalid for target: {e}")
    print("   Consider using a different target or simplifying the circuit")

except ProviderUnavailableError as e:
    print(f"⚠️  Provider temporarily unavailable: {e}")
    print("   Try again later or use a different provider")

except QuotaExceededError as e:
    print(f"💰 Quota/credits exceeded: {e}")
    print("   Add more credits or wait for quota reset")

except AzureQuantumError as e:
    print(f"🔧 Azure Quantum error: {e}")
    print("   Check Azure Quantum status page for outages")

Best Practices

1. Start with Simulators

# Always test on simulators first (free!)
targets_in_order = [
    "ionq.simulator",      # Free, instant
    "ionq.aria-1",         # Paid QPU
]

for target in targets_in_order:
    result = client.azure_quantum.execute(circuit=circuit, target=target, shots=100)
    print(f"{target}: {result.counts}")

2. Use Appropriate Shot Counts

# Simulators: Many shots (free)
simulator_result = client.azure_quantum.execute(
    circuit=circuit,
    target="ionq.simulator",
    shots=10000
)

# QPU: Fewer shots (expensive)
qpu_result = client.azure_quantum.execute(
    circuit=circuit,
    target="ionq.aria-1",
    shots=100  # Usually sufficient for most applications
)

3. Monitor Costs

# Track spending
from softqcos_sdk import QCOSClient

client = QCOSClient()

# Get usage summary
usage = client.usage.get_azure_quantum_summary()
print(f"This month: €{usage.current_month_eur:.2f}")
print(f"Remaining budget: €{usage.remaining_budget_eur:.2f}")

Next Steps

• Batch Processing - Process many circuits efficiently
• VQE Chemistry - Run VQE on real hardware
• Error Handling - Production error handling patterns