Installation¶

Overview¶

FastQSim is a thin, low-dependency HTTP client for submitting OpenQASM 3.0 circuits to the FastQSim platform and retrieving results. The SDK handles job lifecycle operations, long-poll based waiting, and batch submission from a single client API.

Note

Design boundary: the SDK accepts OpenQASM 3.0 strings as circuit input. Native circuit objects from Qiskit, Cirq, or PennyLane are not accepted.

Note

Runtime model: the SDK runs inside an authenticated FastQubit pod/session context and uses a pod-scoped token. It does not perform full user login/session orchestration itself.

Requirements¶

Python 3.8+
A virtual environment is recommended
requests>=2.28

Install from package¶

pip install fastqsim

Install from local source¶

From the QSim directory:

pip install -e .

If you also want to build docs locally:

pip install -r docs/requirements.txt

Environment configuration¶

The SDK client expects runtime environment variables for authentication and endpoint resolution.

Minimal setup (required vars)¶

Set only the runtime pod token to start using the SDK:

export FASTQUBIT_SESSION_TOKEN="fqp_your_pod_token_here"

FASTQUBIT_SESSION_TOKEN is the SDK runtime credential and must be a pod-scoped token in fqp_... format.

Recommended setup (optional vars)¶

Add endpoint and runtime controls for non-default environments:

export FASTQUBIT_ENDPOINT="https://api.qsim.io"
export FASTQSIM_EXECUTION_MODE="cloud"
export FASTQSIM_POLL_INTERVAL_SECONDS="1.0"

Config validation command¶

Use this command to verify required/optional runtime configuration before your first SDK call:

python - <<'PY'
import os

token = os.getenv("FASTQUBIT_SESSION_TOKEN", "")
endpoint = os.getenv("FASTQUBIT_ENDPOINT", "https://api.qsim.io")
mode = os.getenv("FASTQSIM_EXECUTION_MODE", "cloud")

if not token:
    raise SystemExit("Missing FASTQUBIT_SESSION_TOKEN")
if not token.startswith("fqp_"):
    raise SystemExit("FASTQUBIT_SESSION_TOKEN must start with 'fqp_'")
if mode not in {"cloud", "local"}:
    raise SystemExit("FASTQSIM_EXECUTION_MODE must be 'cloud' or 'local'")

print("Configuration looks valid")
print(f"Endpoint: {endpoint}")
print(f"Execution mode: {mode}")
PY

Common setup errors

Missing token: set FASTQUBIT_SESSION_TOKEN before calling fastqsim.init().
Invalid endpoint: verify FASTQUBIT_ENDPOINT points to the correct FastQubit API base URL.
Wrong execution mode: set FASTQSIM_EXECUTION_MODE to cloud or local only.