introduction

Getting started

From pip install to your first routed hardware run in about five minutes. CatState is BYOA — before hardware runs, you'll store a provider credential in the vault.

1. Install

The SDK is dependency-light (httpx, pydantic, websockets). Install the framework adapter you need as an extra:

terminalsh

pip install catstate            # core SDK (superfermion-native)
pip install "catstate[qiskit]"    # Qiskit BackendV2 adapter
pip install "catstate[pennylane]" # PennyLane device plugin

2. Connect

Create an account, generate an org API key, and export it. catstate.connect() reads it from the environment:

terminalsh

export CATSTATE_API_KEY="cs_live_..."

3. Run your first circuit

first_run.pypy

1import superfermion as sf
2import catstate
3 
4cs = catstate.connect()
5 
6circuit = sf.Circuit(2).h(0).cx(0, 1)
7 
8with cs.experiment("bell_benchmark"):
9    result = sf.run(circuit, device=cs("best"), shots=4096)
10 
11print(result.counts)
12# {'00': 2041, '11': 2055}

Everything inside the with block is tracked to the experiment. Scope is visible in indentation — no hidden global state, no init/finish pairs.

Next steps

Store a provider credential in the credential vault to unlock hardware runs.
Learn how sub-keys cap spend for students and CI.
Pick a routing strategy — best, cheapest, or fastest.