Commutator Studios Python SDK

Commutator SDK is the official Python client for the Commutator Studios quantum ecosystem. It provides a seamless, developer-friendly interface to integrate quantum workloads, optimization engines, and identity management natively into your Python tech stack.

By connecting to the Centralized API Gateway (commutator.app), this SDK handles authentication, rate-limiting, and billing checks automatically, allowing you to focus on building quantum-accelerated applications.

Features

• Quantum Fleet Management: Discover, list, and check the status of available quantum backends (e.g., ibm_berlin, ibmq_qasm_simulator). Automatically synchronizes hardware catalog using the authenticated user's quantum provider credentials.
• Hardware & Algorithmic Recommendations: Interface directly with cs-optimizer to get smart recommendations for hardware and optimization levels (e.g., VQE) before you run your circuits.
• Job Execution & Polling: Submit quantum circuits, execute jobs on actual quantum hardware, and download results natively into Python objects.
• Standardized Error Handling: Detailed, structured exceptions (APIError, ValidationError, AuthenticationError) for predictable and easy debugging.
• ...and more!

Installation

The SDK requires Python 3.11+. You can install it directly from PyPI using pip:

pip install commutator-sdk

Quick Start

Here is a simple example showing how to authenticate, create a job, execute a circuit, and fetch the results.

1. Authentication

You can authenticate using your API Key or Username/Password.

from commutator.client import CommutatorClient

# Initialize the client (Environment is auto-detected)
client = CommutatorClient(api_key="your_api_key_here")

2. Submitting a Quantum Job

Submit your quantum circuit JSON and execute it on a selected backend.

import json
from commutator import ClassicalOptimizer

# 1. Create the Job
job = client.create_job(
    name="My First VQE Run",
    algorithm="VQE",
    file_path="circuit.json"
)
job_id = job["id"]
print(f"Job created successfully: {job_id}")

# 2. Execute the Job with Classical Numerical Optimizer (e.g. COBYLA or Simplex)
client.execute_job(
    job_id=job_id,
    backend="ibm_berlin",
    optimization_level=3,
    optimizer=ClassicalOptimizer.COBYLA  # or "cobyla" / ClassicalOptimizer.SIMPLEX
)
print("Job dispatched to the quantum backend!")

3. Optimizer Recommendations

Not sure which backend or optimization level to use? Ask the Recommendation Engine!

recommendations = client.optimizer.recommend(
    job_id="your_job_id",
    target_backends=["ibm_kingston", "ibm_brisbane"]  # Optional: omit to evaluate all fleet backends
)

print(f"Recommended Backend: {recommendations[0]['provider']}")

Error Handling & Exception Reference

When executing quantum simulation jobs, the SDK automatically inspects the API response errorCode and raises typed Python exceptions providing human-readable diagnostic remedies:

from commutator.client import CommutatorClient
from commutator.exceptions import (
    SimulationOOMError,
    SimulationTimeoutError,
    ProviderAuthenticationError,
    JobFailedError
)

client = CommutatorClient(api_key="your_api_key")

try:
    job_details = client.jobs.get(job_id="5bacd027-267d-4c8e-94c4-5348c48880b3")
except SimulationOOMError as e:
    print(f"❌ Memory Error [{e.error_code}]: {e.message}")
    print(f"💡 Actionable Remedy: {e.remedy}")
except SimulationTimeoutError as e:
    print(f"⏱️ Job Timed Out [{e.error_code}]: {e.message}")
    print(f"💡 Actionable Remedy: {e.remedy}")
except JobFailedError as e:
    print(f"⚠️ Job Execution Failed [{e.error_code}]: {e.message}")

Supported Exception Mapping

Advanced Usage

For comprehensive documentation, including detailed API reference, Identity Management (list_api_keys, get_audit_logs), and advanced configuration options, please refer to the official Commutator Studios Documentation.

License

Copyright © 2026 Commutator Studios GmbH. All rights reserved.