Skip to main content

Your First Circuit

This tutorial walks you through executing your first quantum circuit with QCOS.

The Bell State​

We'll create and execute a Bell state - a fundamental quantum circuit that demonstrates entanglement:

     ┌───┐
q_0: ┤ H ├──■──
     └───┘┌─┴─┐
q_1: ─────┤ X ├
          └───┘

This circuit:

  1. Applies a Hadamard gate to put qubit 0 in superposition
  2. Applies a CNOT gate to entangle qubits 0 and 1
  3. Measures both qubits

Method 1: Python SDK​

Basic Execution​

from softqcos_sdk import QCOSClient

# Initialize client
client = QCOSClient()

# Define Bell state circuit in OpenQASM
bell_circuit = """
OPENQASM 2.0;
include "qelib1.inc";
qreg q[2];
creg c[2];
h q[0];
cx q[0],q[1];
measure q -> c;
"""

# Execute circuit
result = client.execute(
    qasm=bell_circuit,
    shots=1024
)

# View results
print(f"Job ID: {result.job_id}")
print(f"Status: {result.status}")
print(f"Counts: {result.counts}")
# {'00': 512, '11': 512}

With Qiskit Integration​

from softqcos_sdk import QCOSClient
from qiskit import QuantumCircuit

# Create circuit using Qiskit
qc = QuantumCircuit(2, 2)
qc.h(0)
qc.cx(0, 1)
qc.measure([0, 1], [0, 1])

# Execute via QCOS (default backend)
client = QCOSClient()
result = client.execute_qiskit(qc, shots=1024)

print(result.counts)
# {'00': 512, '11': 512}

Multi-Supplier Execution (New in v2.1)​

from softqcos_sdk import QCOSClient

client = QCOSClient()

# Execute on Azure Quantum IonQ
result_ionq = client.execute_on_backend(
    qasm=bell_circuit,
    backend="ionq.simulator",
    supplier="azure_quantum",
    shots=1024
)
print(f"IonQ: {result_ionq.counts}")

# Execute on IBM Quantum
result_ibm = client.execute_on_backend(
    qasm=bell_circuit,
    backend="ibm_kyoto",
    supplier="ibm_quantum",
    shots=1024
)
print(f"IBM: {result_ibm.counts}")

# Execute on AWS Braket
result_braket = client.execute_on_backend(
    qasm=bell_circuit,
    backend="sv1",
    supplier="braket",
    shots=1024
)
print(f"Braket: {result_braket.counts}")

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

See Multi-Supplier Guide for full details.

Async Execution​

import asyncio
from softqcos_sdk import AsyncQCOSClient

async def run_bell_state():
    async with AsyncQCOSClient() as client:
        # Submit job
        job = await client.submit(
            qasm=bell_circuit,
            shots=1024
        )
        print(f"Submitted: {job.job_id}")

        # Wait for result
        result = await job.wait()
        print(f"Result: {result.counts}")

asyncio.run(run_bell_state())

Method 2: Command Line​

Create Circuit File​

# bell.qasm
cat > bell.qasm << 'EOF'
OPENQASM 2.0;
include "qelib1.inc";
qreg q[2];
creg c[2];
h q[0];
cx q[0],q[1];
measure q -> c;
EOF

Execute Circuit​

# Submit and wait for result
softqcos execute bell.qasm --shots 1024

# Output:
# ✓ Job submitted: job_abc123
# ⏳ Waiting for result...
# ✓ Completed in 1.2s
#
# Results:
# ┌─────────┬───────┬─────────┐
# │ State   │ Count │ Percent │
# ├─────────┼───────┼─────────┤
# │ 00      │ 512   │ 50.0%   │
# │ 11      │ 512   │ 50.0%   │
# └─────────┴───────┴─────────┘

Async Execution​

# Submit without waiting
softqcos execute bell.qasm --shots 1024 --no-wait
# ✓ Job submitted: job_abc123

# Check status later
softqcos status job_abc123
# Status: completed
# Duration: 1.2s

# Get results
softqcos results job_abc123
# {'00': 512, '11': 512}

Method 3: REST API​

Submit Job (Legacy LUMI)​

curl -X POST https://sqt-prod-azure-api-ca.icybay-7dfb32ea.westeurope.azurecontainerapps.io/execute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "qasm": "OPENQASM 2.0; include \"qelib1.inc\"; qreg q[2]; creg c[2]; h q[0]; cx q[0],q[1]; measure q -> c;",
    "shots": 1024
  }'

Response:

{
  "job_id": "lumi_abc123",
  "status": "queued",
  "message": "Job queued for GPU execution on LUMI",
  "estimated_time_seconds": 30
}

Multi-Supplier Execution (New in v2.1)​

Execute on Azure Quantum​

curl -X POST https://sqt-prod-azure-api-ca.icybay-7dfb32ea.westeurope.azurecontainerapps.io/api/v1/azure_quantum/execute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "qasm": "OPENQASM 2.0; include \"qelib1.inc\"; qreg q[2]; creg c[2]; h q[0]; cx q[0],q[1]; measure q -> c;",
    "backend": "ionq.simulator",
    "shots": 1024
  }'

Execute on IBM Quantum​

curl -X POST https://sqt-prod-azure-api-ca.icybay-7dfb32ea.westeurope.azurecontainerapps.io/api/v1/ibm_quantum/execute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "qasm": "OPENQASM 2.0; include \"qelib1.inc\"; qreg q[2]; creg c[2]; h q[0]; cx q[0],q[1]; measure q -> c;",
    "backend": "ibm_kyoto",
    "shots": 1024
  }'

Execute on AWS Braket​

curl -X POST https://sqt-prod-azure-api-ca.icybay-7dfb32ea.westeurope.azurecontainerapps.io/api/v1/braket/execute \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "qasm": "OPENQASM 2.0; include \"qelib1.inc\"; qreg q[2]; creg c[2]; h q[0]; cx q[0],q[1]; measure q -> c;",
    "device_arn": "arn:aws:braket:us-east-1::device/quantum-simulator/amazon/sv1",
    "shots": 1024
  }'

See API Reference for all endpoints.

Check Status​

# Legacy LUMI job
curl https://sqt-prod-azure-api-ca.icybay-7dfb32ea.westeurope.azurecontainerapps.io/status/lumi_abc123 \
  -H "X-API-Key: your-api-key"

# Azure Quantum job
curl https://sqt-prod-azure-api-ca.icybay-7dfb32ea.westeurope.azurecontainerapps.io/api/v1/azure_quantum/status/azure_job_123 \
  -H "X-API-Key: your-api-key"

# IBM Quantum job
curl https://sqt-prod-azure-api-ca.icybay-7dfb32ea.westeurope.azurecontainerapps.io/api/v1/ibm_quantum/status/ibm_job_123 \
  -H "X-API-Key: your-api-key"

# AWS Braket job
curl https://sqt-prod-azure-api-ca.icybay-7dfb32ea.westeurope.azurecontainerapps.io/api/v1/braket/status/arn:aws:braket:us-east-1:123456789012:quantum-task/task-abc123 \
  -H "X-API-Key: your-api-key"

Response:

{
  "job_id": "lumi_abc123",
  "status": "completed",
  "result": {
    "counts": {"00": 512, "11": 512},
    "num_qubits": 2,
    "shots": 1024,
    "execution_time_seconds": 0.05,
    "backend": "cuStateVec",
    "device": "NVIDIA A100"
  }
}

List Available Providers​

# List Azure Quantum providers
curl https://sqt-prod-azure-api-ca.icybay-7dfb32ea.westeurope.azurecontainerapps.io/api/v1/azure_quantum/providers \
  -H "X-API-Key: your-api-key"

# List IBM Quantum backends
curl https://sqt-prod-azure-api-ca.icybay-7dfb32ea.westeurope.azurecontainerapps.io/api/v1/ibm_quantum/backends \
  -H "X-API-Key: your-api-key"

# List AWS Braket devices
curl https://sqt-prod-azure-api-ca.icybay-7dfb32ea.westeurope.azurecontainerapps.io/api/v1/braket/devices \
  -H "X-API-Key: your-api-key"

Understanding Results​

Result Object​

result = client.execute(qasm=circuit, shots=1024)

# Basic properties
result.job_id          # "abc123-def456-ghi789"
result.status          # "completed"
result.counts          # {'00': 512, '11': 512}

# Execution metadata
result.num_qubits      # 2
result.shots           # 1024
result.execution_time  # 0.05 seconds
result.backend         # "cuStateVec"
result.device          # "NVIDIA A100"

# Timestamps
result.created_at      # datetime
result.completed_at    # datetime

Probability Distribution​

# Get probabilities instead of counts
probs = result.probabilities()
print(probs)
# {'00': 0.5, '11': 0.5}

# Most likely state
print(result.most_likely_state())
# '00' (or '11' with 50% probability)

Visualization​

from softqcos.visualization import plot_histogram

# Plot histogram
plot_histogram(result.counts, title="Bell State Results")

Larger Circuits​

GHZ State (5 qubits)​

ghz_5 = """
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;
"""

result = client.execute(qasm=ghz_5, shots=2048)
print(result.counts)
# {'00000': 1024, '11111': 1024}

50-Qubit Circuit (Pro Tier)​

# Generate 50-qubit GHZ state
qubits = 50
qasm = f"""
OPENQASM 2.0;
include "qelib1.inc";
qreg q[{qubits}];
creg c[{qubits}];
h q[0];
"""
for i in range(qubits - 1):
    qasm += f"cx q[{i}],q[{i+1}];\n"
qasm += "measure q -> c;"

result = client.execute(qasm=qasm, shots=1024)
print(f"Execution time: {result.execution_time:.2f}s")
# Execution time: 2.45s

Error Handling​

from softqcos_sdk import QCOSClient, QCOSError, RateLimitError, QuotaExceededError

client = QCOSClient()

try:
    result = client.execute(qasm=circuit, shots=1024)
except RateLimitError as e:
    print(f"Rate limit hit. Reset at: {e.reset_time}")
except QuotaExceededError as e:
    print(f"Quota exceeded: {e.message}")
    print(f"Your limit: {e.limit}, Requested: {e.requested}")
except QCOSError as e:
    print(f"Error: {e.message}")

Next Steps​