Installation Guide

The softqcos-sdk requires Python 3.10, 3.11, 3.12, or 3.13. We highly recommend installing it within a clean virtual environment (venv or conda) to avoid conflicts with other scientific libraries.

1. PyPI Installation & Extras

Depending on your use case, you can install the base client or include pre-packaged dependencies (extras) for local simulations or advanced plotting.

Base Installation

Installs the low-level HTTP transport client, models, and core API wrapper. Ideal for thin workers, cloud pipelines, or servers offloading all work:

Simulation Bundle

Adds local simulator support (installs Qiskit Aer, NumPy, and SciPy). Needed to run simulations locally on your machine without querying the cloud:
Installs all optional components, including local simulators and rendering dependencies (matplotlib, pandas, and visualizers):

2. Offline / Local Wheel Installation

For high-security scientific labs or air-gapped environments where outbound internet access is blocked, you can install precompiled wheels directly. If you have built or downloaded the wheels to your workstation, navigate to the target directory and install them:
Note: Make sure to satisfy dependencies like requests and urllib3 using your internal corporate mirror or package caching servers.

3. Configuration & Auth Parameters

When you instantiate QCOSClient(), it resolves configuration values using the following priority:
  1. Explicit Parameters: Values passed directly in the constructor (e.g. QCOSClient(api_key="...")).
  2. Environment Variables: Reads standard environment settings in the terminal.
  3. Local CLI Config: Reads keys and configurations saved by the CLI inside ~/.softqcos/config.json.
Add the following environment variables to your shell profile (~/.zshrc or ~/.bashrc) for seamless authentication:

4. Verification Check

To confirm that the SDK is installed correctly and can communicate with either your local daemon or the cloud gateway, run this quick check: