Skip to main content

SDK Capabilities

Complete reference of all capabilities offered by the softqcos-sdk Python package.

Installation​

# SDK only
pip install softqcos-sdk

# Complete suite (includes CLI and QuantumLock)
pip install softqcos

Core Classes​

QCOSClient​

The main client for interacting with the QCOS API.

from softqcos_sdk import QCOSClient

client = QCOSClient(
    api_key="your-api-key",           # Required (or QCOS_API_KEY env var)
    base_url="https://api.softquantus.com",  # Optional
    timeout=60.0,                      # Request timeout (seconds)
    max_retries=3,                     # Automatic retry count
    license_file="/path/to/license.lic",  # Optional license file
    license_key="QCOS-XXXX-XXXX",     # Optional license key
    validate_license=True,             # Validate license on init
)

AsyncQCOSClient​

Async version for high-performance applications.

from softqcos_sdk import AsyncQCOSClient

async def main():
    client = AsyncQCOSClient(api_key="your-key")
    result = await client.execute(qasm=circuit, shots=1024)

Circuit Execution​

execute()​

Execute a quantum circuit synchronously (blocks until completion).

result = client.execute(
    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
)

print(result.counts)      # {'00': 512, '11': 512}
print(result.job_id)      # 'job_abc123'
print(result.status)      # 'completed'

Returns: JobResult

FieldTypeDescription
job_idstrUnique job identifier
statusstrJob status: completed, failed
countsdictMeasurement counts
metadatadictExecution metadata

submit()​

Submit a circuit asynchronously (returns immediately).

job = client.submit(qasm=circuit, shots=1024)

print(job.job_id)    # 'job_abc123'
print(job.status)    # 'queued'

Returns: CircuitJob

get_status()​

Get the status of a submitted job.

status = client.get_status(job_id="job_abc123")

print(status.status)     # 'processing' | 'completed' | 'failed'
print(status.progress)   # 0.75 (if available)

get_result()​

Get the result of a completed job.

result = client.get_result(job_id="job_abc123")

print(result.counts)
print(result.metadata)

wait_for_result()​

Wait for a job to complete with polling.

result = client.wait_for_result(
    job_id="job_abc123",
    timeout=300.0,        # Max wait time (seconds)
    poll_interval=2.0     # Check every N seconds
)

Multi-Supplier Support​

list_providers()​

List available quantum providers from a specific supplier.

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

# IBM Quantum backends
ibm_backends = client.list_providers("ibm_quantum")

# AWS Braket devices
braket_devices = client.list_providers("braket")

Supported Suppliers:

SupplierProvidersMax Qubits
azure_quantumIonQ, Rigetti, Quantinuum, PASQAL100
ibm_quantumSimulators, Kyoto, Osaka, Brisbane127
braketSV1, IonQ, Rigetti, QuEra, OQC, IQM256

execute_on_backend()​

Execute a circuit on a specific backend.

# Execute on Azure Quantum IonQ
result = client.execute_on_backend(
    qasm=circuit,
    backend="ionq.simulator",
    supplier="azure_quantum",
    shots=1024
)

# Execute on IBM Quantum
result = client.execute_on_backend(
    qasm=circuit,
    backend="ibm_kyoto",
    supplier="ibm_quantum",
    shots=1024
)

# Execute on AWS Braket
result = client.execute_on_backend(
    qasm=circuit,
    backend="Aquila",
    supplier="braket",
    shots=1024
)

Licensing​

license()​

Get the license object for the client.

lic = client.license()
print(lic.info)

license_info()​

Get license information as dictionary.

info = client.license_info()
print(info['type'])        # 'enterprise'
print(info['expires_at'])  # '2026-12-31'
print(info['features'])    # ['core', 'optimization', 'multi-supplier']

has_feature()​

Check if a feature is licensed.

if client.has_feature("optimization"):
    result = client.optimize(circuit)

require_feature()​

Require a feature or raise exception.

client.require_feature("enterprise")  # Raises FeatureNotLicensed if not available

QCOSLicense Class​

Standalone license management.

from softqcos_sdk.licensing import QCOSLicense, LicenseError

# From file
lic = QCOSLicense(license_file="~/.softqcos/license.lic")

# From key
lic = QCOSLicense(license_key="QCOS-XXXX-XXXX-XXXX")

# Validate
if lic.validate():
    print("License valid!")
    print(lic.info)

Models​

JobResult​

@dataclass
class JobResult:
    job_id: str
    status: str           # 'completed' | 'failed'
    counts: dict          # {'00': 512, '11': 512}
    metadata: dict        # Execution metadata
    created_at: datetime
    completed_at: datetime
    error: Optional[str]

CircuitJob​

@dataclass
class CircuitJob:
    job_id: str
    status: str           # 'queued' | 'processing'
    created_at: datetime

ProviderInfo​

@dataclass
class ProviderInfo:
    id: str
    name: str
    num_qubits: int
    targets: list[str]
    description: str
    cost_model: str

SupplierInfo​

@dataclass
class SupplierInfo:
    id: str
    name: str
    status: str
    providers: list[ProviderInfo]

BackendInfo​

@dataclass
class BackendInfo:
    id: str
    name: str
    supplier: str
    num_qubits: int
    status: str

Exceptions​

ExceptionDescription
QCOSErrorBase exception for all QCOS errors
AuthenticationErrorInvalid API key or authentication failed
ValidationErrorInvalid circuit or parameters
JobNotFoundErrorJob ID does not exist
TimeoutErrorRequest or job timed out
RateLimitErrorAPI rate limit exceeded
LicenseErrorLicense validation failed
FeatureNotLicensedFeature not included in license
from softqcos_sdk import QCOSError, AuthenticationError, RateLimitError

try:
    result = client.execute(qasm=circuit, shots=1024)
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except QCOSError as e:
    print(f"QCOS error: {e}")

Environment Variables​

VariableDescription
QCOS_API_KEYAPI key for authentication
QCOS_API_URLBase URL for API (default: https://api.softquantus.com)
QCOS_LICENSE_KEYLicense key
QCOS_LICENSE_FILEPath to license file
QCOS_TIMEOUTDefault timeout in seconds

Complete Example​

from softqcos_sdk import QCOSClient
import os

# Initialize client
client = QCOSClient(
    api_key=os.getenv("QCOS_API_KEY"),
    validate_license=True
)

# Check license
if client.has_feature("multi-supplier"):
    print("Multi-supplier access enabled!")

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

# Execute on default backend
result = client.execute(qasm=bell_state, shots=2048)
print(f"Job: {result.job_id}")
print(f"Counts: {result.counts}")

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

# Execute on specific backend
result = client.execute_on_backend(
    qasm=bell_state,
    backend="ionq.simulator",
    supplier="azure_quantum",
    shots=1024
)
print(f"IonQ result: {result.counts}")

© 2024-2026 SoftQuantus innovative OÜ. All Rights Reserved.