Skip to main content

Tutorial: Your First Quantum Job

Submit a Bell state circuit, monitor its execution, and retrieve verified results with evidence.

Time: 10 minutes · Prerequisites: API key configured

Step 1 — Write a Bell State Circuit​

Create a file called bell.qasm:

bell.qasm
OPENQASM 2.0;
include "qelib1.inc";

qreg q[2];
creg c[2];

h q[0];
cx q[0], q[1];

measure q[0] -> c[0];
measure q[1] -> c[1];

This circuit creates a Bell state — two maximally entangled qubits.

Step 2 — Validate the Circuit​

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

from softqcos_sdk import QCOSClient

client = QCOSClient()

with open("bell.qasm") as f:
    qasm = f.read()

validation = client.circuits.validate(qasm)
print(f"Valid: {validation['valid']}")
print(f"Qubits: {validation['num_qubits']}, Depth: {validation['depth']}")
 
softqcos circuits validate bell.qasm
 
curl -X POST https://api.softquantus.com/api/v2/circuits/validate \
  -H "Authorization: Bearer $QCOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"qasm": "OPENQASM 2.0; ..."}'

Step 3 — Submit the Job​

job = client.jobs.submit(qasm, shots=4096, backend="aer_simulator")
print(f"Job ID: {job['job_id']}")
print(f"Status: {job['status']}")
 
softqcos jobs submit bell.qasm --shots 4096 --backend aer_simulator
# Output: Job abc123def456 submitted (status: PENDING)

Step 4 — Monitor Execution​

import time

while True:
    status = client.jobs.get(job["job_id"])
    print(f"Status: {status['status']}")

    if status["status"] in ("COMPLETED", "FAILED", "CANCELLED"):
        break

    time.sleep(2)

Or use the built-in wait helper:

completed = client.jobs.wait(job["job_id"], timeout=300)
print(f"Final status: {completed['status']}")
 
# Poll manually
softqcos jobs get abc123def456

# Or wait for completion
softqcos jobs wait abc123def456 --timeout 300

Step 5 — Get Results​

results = client.jobs.results(job["job_id"])

print("Measurement counts:")
for state, count in results["counts"].items():
    print(f"  |{state}⟩: {count}")

# Expected output for Bell state:
#   |00⟩: ~2048
#   |11⟩: ~2048
 
softqcos jobs results abc123def456

# JSON output for scripting
softqcos jobs results abc123def456 -o json | jq '.counts'

Step 6 — Verify with Evidence​

Every QCOS job produces a cryptographically signed evidence bundle.

evidence = client.jobs.evidence(job["job_id"])
print(f"Hash: {evidence['hash']}")
print(f"Signature: {evidence['signature'][:64]}...")

# Verify integrity
verification = client.jobs.verify(job["job_id"])
print(f"Valid: {verification['valid']}")
print(f"Signer: {verification['signer']}")
 
# Get evidence
softqcos jobs evidence abc123def456

# Verify
softqcos jobs verify abc123def456
# Output: ✓ Evidence valid (SHA-256, signed by SoftQuantus CA)

Step 7 — All-in-One (Shortcut)​

For quick experiments, use execute (SDK) or run (CLI) which combines submit + wait + results:

result = client.jobs.execute(qasm, shots=4096, backend="aer_simulator")
print(result["counts"])  # {"00": 2048, "11": 2048}
 
softqcos jobs run bell.qasm --shots 4096 --backend aer_simulator

What's Next?​