Skip to main content

Migration Guide: QCOS API v1 → v2

Overview​

QCOS API v2 introduces major enhancements while maintaining backward compatibility with v1. This guide helps you migrate to v2 and take advantage of new features.

Breaking Changes​

None! 🎉​

All v1 endpoints remain functional in v2. Existing code will continue to work without modifications.

However, we recommend migrating to v2 features for:

  • Better performance
  • Real quantum hardware access
  • Advanced optimization
  • Cost transparency

New Features​

1. Azure Quantum Integration​

Before (v1):

# Only LUMI GPU simulator
result = softqcos.execute(circuit, backend="aer_mps", shots=1024)

After (v2):

# Real quantum hardware!
result = softqcos.azure_quantum.execute(
    circuit=circuit,
    target="ionq.aria",  # 29-qubit QPU
    shots=1024,
    confirm_cost=True
)

2. Circuit Optimization​

Before (v1):

# Manual optimization
from qiskit.transpiler import transpile
optimized = transpile(circuit, optimization_level=3)
result = softqcos.execute(qasm.dumps(optimized))

After (v2):

# Automatic optimization for target backend
optimized = softqcos.optimize(
    circuit=circuit,
    objective="max_fidelity",
    target_backend="ionq"
)
print(f"Reduced depth by {optimized.improvements['depth_reduction']}")
result = softqcos.execute(optimized.circuit)

3. Cost Estimation​

Before (v1):

# No cost estimation - charges unknown
result = softqcos.execute(circuit, backend="gpu")

After (v2):

# Transparent cost estimation
estimate = softqcos.estimate_cost(
    circuit=circuit,
    backend="azure_quantum_ionq",
    shots=1024
)

print(f"Cost: €{estimate.estimated_cost_eur:.2f}")
print(f"Time: {estimate.estimated_time_seconds}s")

# Proceed if acceptable
if estimate.estimated_cost_eur < 5:
    result = softqcos.execute(circuit, backend="azure_quantum_ionq")

4. Batch Processing​

Before (v1):

# Sequential execution (slow)
results = []
for circuit in circuits:
    result = softqcos.execute(circuit)
    results.append(result)
# Takes 10x longer for 10 circuits

After (v2):

# Parallel batch execution
batch = softqcos.batch([
    {"circuit": c, "backend": "aer", "shots": 1024}
    for c in circuits
], parallel=True)

# Check status
status = softqcos.get_batch_status(batch.batch_id)
# ~10x faster!

5. Circuit Analysis​

Before (v1):

# Manual circuit inspection
from qiskit import QuantumCircuit
qc = QuantumCircuit.from_qasm_str(circuit)
print(f"Qubits: {qc.num_qubits}")
print(f"Depth: {qc.depth()}")

After (v2):

# Comprehensive analysis
analysis = softqcos.analyze(circuit)
print(f"Qubits: {analysis.num_qubits}")
print(f"Depth: {analysis.depth}")
print(f"Complexity: {analysis.complexity}")
print(f"Suggested backends: {analysis.suggested_backends}")
print(f"Warnings: {analysis.warnings}")

Migration Examples​

Example 1: VQE Parameter Sweep​

v1 Code:

import numpy as np
from qcos_sdk import QCOS

softqcos= QCOS(api_key="...")
results = []

for theta in np.linspace(0, np.pi, 20):
    circuit = create_vqe_circuit(theta)
    result = softqcos.execute(circuit, backend="aer", shots=1024)
    results.append(result)
    # Takes ~20 minutes (1 min per circuit)

v2 Code (Optimized):

import numpy as np
from qcos_sdk import QCOS

softqcos= QCOS(api_key="...")

# Create all experiments
experiments = []
for theta in np.linspace(0, np.pi, 20):
    circuit = create_vqe_circuit(theta)
    experiments.append({
        "circuit": circuit,
        "backend": "aer",
        "shots": 1024
    })

# Execute in parallel batch
batch = softqcos.batch(experiments, parallel=True)

# Wait for completion
status = softqcos.wait_for_batch(batch.batch_id)
results = status.results
# Takes ~2 minutes (10x speedup!)

Example 2: Production Circuit Execution​

v1 Code:

# No optimization, no cost check
result = softqcos.execute(circuit, backend="aer_mps", shots=4096)

v2 Code (Best Practices):

# Step 1: Analyze circuit
analysis = softqcos.analyze(circuit)
print(f"Circuit complexity: {analysis.complexity}")
print(f"Recommended backends: {analysis.suggested_backends}")

# Step 2: Optimize for target backend
optimized = softqcos.optimize(
    circuit=circuit,
    objective="balanced",
    target_backend="ionq"
)

print(f"Optimization improvements:")
print(f"  Depth: {optimized.improvements['depth_reduction']}")
print(f"  Gates: {optimized.improvements['gate_reduction']}")

# Step 3: Estimate cost
estimate = softqcos.estimate_cost(
    circuit=optimized.circuit,
    backend="azure_quantum_ionq",
    shots=4096
)

print(f"Estimated cost: €{estimate.estimated_cost_eur:.2f}")

# Step 4: Execute with cost confirmation
if estimate.estimated_cost_eur < 10:
    result = softqcos.azure_quantum.execute(
        circuit=optimized.circuit,
        target="ionq.aria",
        shots=4096,
        confirm_cost=True
    )
else:
    print("Cost too high - using simulator instead")
    result = softqcos.execute(optimized.circuit, backend="aer_mps", shots=4096)

Example 3: Real-time Notifications​

v1 Code:

# Poll for results
job = softqcos.execute(circuit, backend="aer_mps")

import time
while True:
    status = softqcos.get_status(job.job_id)
    if status.status == "completed":
        result = status.result
        break
    time.sleep(5)
    # Inefficient polling

v2 Code (Webhooks):

# Setup webhook once
webhook = softqcos.create_webhook(
    url="https://your-server.com/softqcos-webhook",
    events=["job.completed", "job.failed"],
    secret="your-secret"
)

# Execute job
job = softqcos.execute(circuit, backend="aer_mps")

# Your server receives webhook when done
# No polling needed!

Webhook handler:

from flask import Flask, request
import hmac
import hashlib

app = Flask(__name__)

@app.route('/softqcos-webhook', methods=['POST'])
def qcos_webhook():
    # Verify signature
    signature = request.headers.get('X-QCOS-Signature')
    payload = request.get_data()
    expected = hmac.new(
        b'your-secret',
        payload,
        hashlib.sha256
    ).hexdigest()

    if signature != f"sha256={expected}":
        return "Invalid signature", 401

    # Process event
    event = request.json
    if event['event'] == 'job.completed':
        process_result(event['data']['result'])

    return "OK", 200

Provider Migration​

Switching Backends​

v1 Backends:

  • aer - Statevector simulator (25 qubits)
  • aer_mps - Matrix product state (100 qubits)
  • cirq - Google Cirq simulator
  • pennylane - PennyLane simulator
  • braket - AWS Braket (limited)

v2 Backends (All v1 + Azure Quantum):

  • All v1 backends still work
  • azure_quantum_ionq - IonQ Aria/Harmony
  • azure_quantum_rigetti - Rigetti Aspen
  • azure_quantum_quantinuum - Quantinuum H-Series
  • azure_quantum_pasqal - PASQAL Fresnel

Migration:

# v1
result = softqcos.execute(circuit, backend="aer_mps")

# v2 (same code works)
result = softqcos.execute(circuit, backend="aer_mps")

# v2 (with real hardware)
result = softqcos.execute(circuit, backend="azure_quantum_ionq")

SDK Updates​

Python SDK​

Update:

pip install --upgrade softqcos-sdk

New imports:

from qcos_sdk import QCOS

softqcos= QCOS(api_key="...")

# New v2 APIs
softqcos.optimize(...)
softqcos.batch(...)
softqcos.analyze(...)
softqcos.estimate_cost(...)
softqcos.azure_quantum.execute(...)

JavaScript/TypeScript SDK​

Update:

npm install @softqcos/sdk@latest

New APIs:

import { QCOS } from '@softqcos/sdk';

const softqcos= new QCOS({ apiKey: '...' });

// New v2 APIs
await softqcos.optimize({ ... });
await softqcos.batch({ ... });
await softqcos.analyze({ ... });
await softqcos.estimateCost({ ... });
await softqcos.azureQuantum.execute({ ... });

Pricing Changes​

v1 Pricing​

  • GPU simulation: €0.05-0.50 per job
  • No usage tiers

v2 Pricing​

  • Free Tier: 10 jobs/day, simulators only
  • Professional: €29/month, 100 jobs/day, all providers
  • Enterprise: Custom pricing, unlimited jobs, priority queue

Azure Quantum costs are ADDITIONAL (pay-as-you-go):

  • IonQ: ~€0.90 per circuit
  • Rigetti: ~€0.02 per 10ms
  • Quantinuum: Subscription required
  • PASQAL: ~€288/hour

Deprecation Notice​

Deprecated (but still working):​

None! All v1 APIs continue to work.

Removed in Future v3:​

The following may be removed in v3 (2026):

  • Legacy authentication (API keys in query params)
  • Polling-based status checks (use webhooks instead)
  • Synchronous execution (use async APIs)

Recommended migration path:

# v1 (will be deprecated)
result = softqcos.execute_sync(circuit)

# v2 (recommended)
job = softqcos.execute(circuit)
result = softqcos.wait_for_job(job.job_id)

# v2 (best practice)
webhook = softqcos.create_webhook(...)
job = softqcos.execute(circuit)
# Webhook notifies when done

Testing Your Migration​

1. Run Compatibility Test​

pip install softqcos-sdk --upgrade
python -m softqcos.test_compatibility

2. Compare v1 vs v2 Results​

# Execute same circuit on v1 and v2
circuit = "OPENQASM 2.0; ..."

# v1 backend
result_v1 = softqcos.execute(circuit, backend="aer_mps")

# v2 backend (same simulator)
result_v2 = softqcos.execute(circuit, backend="aer_mps")

# Should be identical
assert result_v1.counts == result_v2.counts

3. Test New Features​

# Test optimization
optimized = softqcos.optimize(circuit, objective="min_depth")
assert optimized.improvements['depth_reduction'] != "0.0%"

# Test batch
batch = softqcos.batch([{"circuit": circuit}], parallel=True)
assert batch.batch_id.startswith("batch_")

# Test Azure Quantum (emulator - free)
estimate = softqcos.estimate_cost(
    circuit=circuit,
    backend="azure_quantum_quantinuum",
    target="quantinuum.emulator"
)
assert estimate.estimated_cost_eur < 1.0  # Emulator is cheap

Performance Improvements​

Execution Time Comparison​

Operationv1v2Improvement
Single simulation (25q)15s5s3x faster
Batch (10 circuits)150s15s10x faster
Circuit optimizationN/A0.2sNew feature
Cost estimationN/A0.1sNew feature

Optimization Results​

Real circuit tested: 50-qubit VQE ansatz

MetricOriginalOptimizedImprovement
Depth24515835.5%
Gate count1,20393722.1%
2-qubit gates41229827.7%
Fidelity (estimated)0.7120.754+4.2pp

Support​

Questions about migration?

Summary Checklist​

  • Update SDK: pip install --upgrade softqcos-sdk
  • Test existing code (should work without changes)
  • Add circuit optimization for production workloads
  • Implement cost estimation for real hardware
  • Migrate sequential jobs to batch API
  • Setup webhooks for real-time notifications
  • Try Azure Quantum emulators (free)
  • Plan QPU usage budget for real hardware
  • Update documentation and examples
  • Train team on new features

Welcome to QCOS API v2! 🚀