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 qcos 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 qcos 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
client = QCOSClient()
result = client.execute_qiskit(qc, shots=1024)

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

Async Execution​

import asyncio
from qcos 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
qcos 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
qcos execute bell.qasm --shots 1024 --no-wait
# ✓ Job submitted: job_abc123

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

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

Method 3: REST API​

Submit Job​

curl -X POST https://api.softquantus.com/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": "abc123-def456-ghi789",
  "status": "queued",
  "message": "Job queued for GPU execution on LUMI",
  "estimated_time_seconds": 30
}

Check Status​

curl https://api.softquantus.com/status/abc123-def456-ghi789 \
  -H "X-API-Key: your-api-key"

Response:

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

Wait for Result​

# Poll until complete (timeout: 60s)
curl "https://api.softquantus.com/results/abc123-def456-ghi789?wait=true&timeout=60" \
  -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 qcos.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 qcos 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​