QCOS Python SDK Reference

Complete reference for the softqcos-sdk Python package.

Installation

pip install softqcos-sdk

With Optional Dependencies

# Visualization support (matplotlib, plotly)
pip install softqcos-sdk[visualization]

# Jupyter integration
pip install softqcos-sdk[jupyter]

# Full installation
pip install softqcos-sdk[full]

Requirements

• Python 3.9+
• Compatible with Qiskit 1.0+, Cirq 1.0+, PennyLane 0.30+

---

QCOSClient

Main client for interacting with QCOS.

Constructor

softqcos.QCOSClient(
    api_key: str = None,
    base_url: str = "https://api.softqcos.softquantus.com/v2",
    timeout: int = 300,
    verify_ssl: bool = True
)

Parameter	Type	Default	Description
api_key	str	None	API key (falls back to QCOS_API_KEY env var)
base_url	str	Production URL	API base URL
timeout	int	300	Request timeout in seconds
verify_ssl	bool	True	Verify SSL certificates

Example

import softqcos

# Using environment variable
client = softqcos.QCOSClient()

# Explicit API key
client = softqcos.QCOSClient(api_key="your-api-key")

# Custom configuration
client = softqcos.QCOSClient(
    api_key="your-api-key",
    timeout=600
)

---

Circuit Execution

run()

Submit a circuit for execution on quantum hardware.

client.run(
    circuit: Union[QuantumCircuit, qiskit.QuantumCircuit, cirq.Circuit],
    backend: str,
    shots: int = 1000,
    optimization_level: int = 2,
    memory: bool = False,
    **options
) -> Job

Parameter	Type	Default	Description
circuit	Circuit	Required	Quantum circuit
backend	str	Required	Backend ID
shots	int	1000	Number of shots
optimization_level	int	2	0-3 optimization level
memory	bool	False	Return per-shot results

Returns: Job object

Example

from softqcos.circuits import QuantumCircuit

# Create circuit
circuit = QuantumCircuit(2, 2)
circuit.h(0)
circuit.cx(0, 1)
circuit.measure_all()

# Submit job
job = client.run(
    circuit,
    backend="ibm_brisbane",
    shots=5000,
    optimization_level=3
)

# Wait for results
result = job.result()
print(result.counts)

---

run_batch()

Submit multiple circuits in a single request.

client.run_batch(
    circuits: List[Circuit],
    backend: str,
    shots: int = 1000,
    **options
) -> BatchJob

Example

circuits = [circuit1, circuit2, circuit3]

batch_job = client.run_batch(
    circuits,
    backend="ibm_brisbane",
    shots=1000
)

# Wait for all results
results = batch_job.results()
for i, result in enumerate(results):
    print(f"Circuit {i}: {result.counts}")

---

Simulation

simulate()

Run circuit on HPC simulator.

client.simulate(
    circuit: Circuit,
    shots: int = 1000,
    noise_model: str = None,
    method: str = "statevector",
    seed: int = None
) -> SimulationResult

Parameter	Type	Default	Description
noise_model	str	None	Backend to emulate
method	str	"statevector"	Simulation method
seed	int	None	Random seed

Example

# Ideal simulation
result = client.simulate(circuit, shots=10000)
print(result.counts)

# With noise model
result = client.simulate(
    circuit,
    shots=10000,
    noise_model="ibm_brisbane"
)
print(result.counts)

---

Circuit Optimization

optimize()

Optimize circuit without execution.

client.optimize(
    circuit: Circuit,
    target_backend: str = None,
    optimization_level: int = 3,
    preserve_layout: bool = False
) -> OptimizationResult

Example

result = client.optimize(
    circuit,
    target_backend="ibm_brisbane",
    optimization_level=3
)

print(f"Original depth: {result.original_depth}")
print(f"Optimized depth: {result.optimized_depth}")
print(f"Reduction: {result.depth_reduction_percent}%")

# Get optimized circuit
optimized_circuit = result.circuit

---

Backend Management

backends()

List available backends.

client.backends(
    provider: str = None,
    status: str = None
) -> List[Backend]

Example

# All backends
backends = client.backends()
for b in backends:
    print(f"{b.id}: {b.qubits} qubits, status={b.status}")

# Filter by provider
ibm_backends = client.backends(provider="ibm")

# Only online backends
online = client.backends(status="online")

---

backend()

Get specific backend details.

client.backend(backend_id: str) -> Backend

Example

backend = client.backend("ibm_brisbane")
print(f"Qubits: {backend.qubits}")
print(f"Queue: {backend.queue_length} jobs")
print(f"Avg wait: {backend.average_wait_minutes} min")
print(f"T1: {backend.calibration.t1_us} μs")

---

Job Management

Job Class

class Job:
    job_id: str
    status: str
    backend: str
    created_at: datetime

    def result(self, timeout: int = 3600) -> Result
    def status(self) -> str
    def cancel(self) -> bool
    def metrics(self) -> JobMetrics

Example

job = client.run(circuit, backend="ibm_brisbane")

# Check status
print(f"Status: {job.status()}")

# Wait for result (blocking)
result = job.result(timeout=1800)

# Or poll manually
while job.status() not in ["completed", "failed", "cancelled"]:
    time.sleep(5)
    print(f"Status: {job.status()}")

---

jobs()

List all jobs.

client.jobs(
    status: str = None,
    backend: str = None,
    limit: int = 50,
    offset: int = 0
) -> List[Job]

Example

# Recent jobs
recent_jobs = client.jobs(limit=10)

# Completed jobs only
completed = client.jobs(status="completed")

# Jobs on specific backend
ibm_jobs = client.jobs(backend="ibm_brisbane")

---

Result Classes

Result

class Result:
    counts: Dict[str, int]
    memory: List[str]  # If memory=True
    metadata: ResultMetadata

    def plot_histogram(self) -> Figure
    def get_statevector(self) -> np.ndarray  # Simulation only

Example

result = job.result()

# Get counts
print(result.counts)  # {'00': 498, '11': 502}

# Plot histogram
result.plot_histogram()

# Access metadata
print(f"Shots: {result.metadata.shots}")
print(f"Backend: {result.metadata.backend}")
print(f"Execution time: {result.metadata.execution_time_ms}ms")

---

QuantumCircuit

QCOS provides its own circuit class for convenience.

Constructor

from softqcos.circuits import QuantumCircuit

circuit = QuantumCircuit(
    num_qubits: int,
    num_clbits: int = None,
    name: str = None
)

Gates

# Single-qubit gates
circuit.h(qubit)      # Hadamard
circuit.x(qubit)      # Pauli-X
circuit.y(qubit)      # Pauli-Y
circuit.z(qubit)      # Pauli-Z
circuit.s(qubit)      # S gate
circuit.t(qubit)      # T gate
circuit.rx(theta, qubit)  # Rotation X
circuit.ry(theta, qubit)  # Rotation Y
circuit.rz(theta, qubit)  # Rotation Z

# Two-qubit gates
circuit.cx(control, target)    # CNOT
circuit.cz(control, target)    # Controlled-Z
circuit.swap(qubit1, qubit2)   # SWAP

# Three-qubit gates
circuit.ccx(c1, c2, target)    # Toffoli
circuit.cswap(c, q1, q2)       # Fredkin

# Measurement
circuit.measure(qubit, clbit)
circuit.measure_all()

Example

from softqcos.circuits import QuantumCircuit
import numpy as np

# GHZ state preparation
circuit = QuantumCircuit(3, 3, name="GHZ")
circuit.h(0)
circuit.cx(0, 1)
circuit.cx(1, 2)
circuit.measure_all()

# Variational circuit
theta = np.pi / 4
circuit = QuantumCircuit(2, 2)
circuit.ry(theta, 0)
circuit.ry(theta, 1)
circuit.cx(0, 1)
circuit.measure_all()

---

Qiskit Integration

from qiskit import QuantumCircuit as QiskitCircuit
import softqcos

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

# Run directly with QCOS
client = softqcos.QCOSClient()
job = client.run(qc, backend="ibm_brisbane")

# Or convert to QCOS circuit
qcos_circuit = softqcos.circuits.from_qiskit(qc)

---

Cirq Integration

import cirq
import softqcos

# Create Cirq circuit
q0, q1 = cirq.LineQubit.range(2)
cirq_circuit = cirq.Circuit([
    cirq.H(q0),
    cirq.CNOT(q0, q1),
    cirq.measure(q0, q1, key='result')
])

# Run directly with QCOS
client = softqcos.QCOSClient()
job = client.run(cirq_circuit, backend="ionq_aria")

---

Account & Usage

usage()

Get current usage statistics.

client.usage() -> Usage

Example

usage = client.usage()
print(f"Quantum minutes: {usage.quantum_minutes.used}/{usage.quantum_minutes.included}")
print(f"Simulation: {usage.simulation_minutes.used}/{usage.simulation_minutes.included}")
print(f"Estimated bill: ${usage.estimated_bill}")

---

Error Handling

import softqcos
from softqcos.exceptions import (
    QCOSError,
    AuthenticationError,
    BackendError,
    QuotaExceededError,
    CircuitValidationError
)

try:
    job = client.run(circuit, backend="ibm_brisbane")
    result = job.result()
except AuthenticationError:
    print("Invalid API key")
except BackendError as e:
    print(f"Backend error: {e.message}")
except QuotaExceededError:
    print("Quota exceeded - upgrade your plan")
except CircuitValidationError as e:
    print(f"Invalid circuit: {e.details}")
except QCOSError as e:
    print(f"QCOS error: {e}")

---

Configuration

Environment Variables

Variable	Description
QCOS_API_KEY	API authentication key
QCOS_BASE_URL	Custom API URL
QCOS_TIMEOUT	Request timeout (seconds)
QCOS_LOG_LEVEL	Logging level (DEBUG, INFO, etc.)

Config File

Create ~/.softqcos/config.yaml:

api_key: your-api-key-here
default_backend: ibm_brisbane
optimization_level: 2
timeout: 300
log_level: INFO

---

Changelog

v2.1.0 (2024-01)

• Added SynapseX integration
• Improved error messages
• Batch job support

v2.0.0 (2023-10)

• Complete SDK rewrite
• Multi-backend support
• New circuit class

See full changelog for details.