Backend¶

The backend system defines the contract that all quantum execution backends must implement.

Architecture¶

Backend (ABC)
├── LocalSimulator      — Pure NumPy, built-in, no dependencies
├── AerBackend          — Qiskit Aer, high-performance simulator
├── IBMBackend          — IBM Quantum real hardware
├── IonQBackend         — IonQ trapped-ion processors (v0.2)
└── CustomBackend       — Your own backend

Core Interfaces¶

Backend ABC¶

Backend ¶

Bases: ABC

Abstract base class for all quantum backends.

Every backend adapter (IBM Quantum, IonQ, GPU simulator, etc.) must implement this interface to integrate with QuantSDK.

Example::

class MyBackend(Backend):
    def run(self, circuit, shots=1024):
        # Submit circuit and return result
        ...

Attributes¶

name `property` ¶

name: str

Backend name (convenience property).

is_simulator `property` ¶

is_simulator: bool

Whether this backend is a simulator.

Functions¶

run `abstractmethod` ¶

run(
    circuit: Circuit, shots: int = 1024, **options: Any
) -> Result

Execute a quantum circuit on this backend.

PARAMETER	DESCRIPTION
`circuit`	The QuantSDK circuit to execute. TYPE: `Circuit`
`shots`	Number of measurement repetitions. TYPE: `int` DEFAULT: `1024`
`**options`	Backend-specific execution options. TYPE: `Any` DEFAULT: `{}`

RETURNS	DESCRIPTION
`Result`	Result object containing measurement outcomes.

info `abstractmethod` ¶

info() -> BackendInfo

Get information about this backend.

RETURNS	DESCRIPTION
`BackendInfo`	BackendInfo with metadata about capabilities and status.

BackendInfo¶

BackendInfo `dataclass` ¶

BackendInfo(
    name: str,
    provider: str,
    num_qubits: int,
    status: BackendStatus = ONLINE,
    is_simulator: bool = False,
    native_gates: frozenset[str] = frozenset(),
    max_shots: int = 100000,
    queue_depth: int = 0,
    metadata: dict[str, Any] = dict(),
)

Metadata about a quantum backend.

ATTRIBUTE	DESCRIPTION
`name`	Unique backend identifier. TYPE: `str`
`provider`	Provider name (e.g., "ibm", "ionq", "simulator"). TYPE: `str`
`num_qubits`	Number of available qubits. TYPE: `int`
`status`	Current operational status. TYPE: `BackendStatus`
`is_simulator`	Whether this is a simulator (vs real hardware). TYPE: `bool`
`native_gates`	Set of natively supported gate names. TYPE: `frozenset[str]`
`max_shots`	Maximum number of shots per job. TYPE: `int`
`queue_depth`	Number of jobs currently queued. TYPE: `int`
`metadata`	Additional backend-specific metadata. TYPE: `dict[str, Any]`

BackendStatus¶

BackendStatus ¶

Bases: Enum

Status of a quantum backend.

Local Simulator¶

The built-in simulator uses pure NumPy tensor contraction. No external dependencies required.

LocalSimulator ¶

Bases: Backend

A local statevector simulator for quantum circuits.

Simulates quantum circuits by computing the full statevector and sampling measurement outcomes. No external dependencies beyond NumPy.

Supports up to ~20 qubits on a typical machine (2^20 = 1M amplitudes).

Example::

from quantsdk.simulators.local import LocalSimulator

sim = LocalSimulator()
result = sim.run(circuit, shots=1000)
print(result.counts)

Functions¶

run ¶

run(
    circuit: Circuit, shots: int = 1024, **options: Any
) -> Result

Execute a circuit on the local simulator.

PARAMETER	DESCRIPTION
`circuit`	The quantum circuit to simulate. TYPE: `Circuit`
`shots`	Number of measurement samples. TYPE: `int` DEFAULT: `1024`
`**options`	seed (int): Random seed for reproducibility. TYPE: `Any` DEFAULT: `{}`

RETURNS	DESCRIPTION
`Result`	Result with measurement counts.

RAISES	DESCRIPTION
`ValueError`	If circuit exceeds MAX_QUBITS.

Usage¶

import quantsdk as qs

# Via qs.run() (recommended)
result = qs.run(circuit, shots=1000)

# Or directly
from quantsdk.simulators.local import LocalSimulator

sim = LocalSimulator()
info = sim.info()
print(f"Max qubits: {info.num_qubits}")  # 24

result = sim.run(circuit, shots=1000, seed=42)

Limitations¶

Maximum 24 qubits (memory constraint)
No noise modeling (use Aer for noise simulation)
CPU only (use GPU backend for large circuits)

IBM Backends¶

Requires pip install quantsdk[ibm].

IBMBackend ¶

IBMBackend(
    token: str | None = None,
    instance: str = "ibm-q/open/main",
    backend_name: str | None = None,
    channel: str = "ibm_quantum_platform",
)

Bases: Backend

Run circuits on IBM Quantum hardware via qiskit-ibm-runtime.

This adapter converts QuantSDK circuits to Qiskit format, submits them to IBM Quantum via the Sampler primitive, and converts results back.

PARAMETER	DESCRIPTION
`token`	IBM Quantum API token. If None, uses saved credentials. TYPE: `str \| None` DEFAULT: `None`
`instance`	IBM Quantum instance (e.g., "ibm-q/open/main"). TYPE: `str` DEFAULT: `'ibm-q/open/main'`
`backend_name`	Specific backend to target (e.g., "ibm_brisbane"). If None, the least-busy backend is selected automatically. TYPE: `str \| None` DEFAULT: `None`
`channel`	Channel type — "ibm_quantum" or "ibm_cloud". TYPE: `str` DEFAULT: `'ibm_quantum_platform'`

Example::

from quantsdk.backends.ibm import IBMBackend
import quantsdk as qs

backend = IBMBackend(token="YOUR_TOKEN")
circuit = qs.Circuit(2).h(0).cx(0, 1).measure_all()
result = backend.run(circuit, shots=4096)
print(result.summary())

Functions¶

run ¶

run(
    circuit: Circuit, shots: int = 4096, **options: Any
) -> Result

Execute a circuit on IBM Quantum hardware.

Uses the Sampler V2 primitive for execution. The circuit is automatically transpiled by IBM's runtime.

PARAMETER	DESCRIPTION
`circuit`	QuantSDK circuit to run. TYPE: `Circuit`
`shots`	Number of measurement shots (default 4096). TYPE: `int` DEFAULT: `4096`
`**options`	Additional options passed to the Sampler. TYPE: `Any` DEFAULT: `{}`

RETURNS	DESCRIPTION
`Result`	QuantSDK Result with measurement counts.

info ¶

info() -> BackendInfo

Get info about the IBM Quantum backend.

available_backends ¶

available_backends(
    simulator: bool = False,
) -> list[BackendInfo]

List available IBM Quantum backends.

PARAMETER	DESCRIPTION
`simulator`	If True, include simulators. Default False. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`list[BackendInfo]`	List of BackendInfo for available backends.

AerBackend ¶

AerBackend(method: str = 'automatic')

Bases: Backend

Run circuits on the local Qiskit Aer simulator.

This is useful for testing and development without an IBM token. Uses the Aer statevector/QASM simulator locally.

PARAMETER	DESCRIPTION
`method`	Simulation method — "automatic", "statevector", "density_matrix", "stabilizer", etc. Default "automatic". TYPE: `str` DEFAULT: `'automatic'`

Example::

from quantsdk.backends.ibm import AerBackend
import quantsdk as qs

backend = AerBackend()
circuit = qs.Circuit(3).h(0).cx(0, 1).cx(1, 2).measure_all()
result = backend.run(circuit, shots=10000)
print(result.counts)

Functions¶

run ¶

run(
    circuit: Circuit, shots: int = 1024, **options: Any
) -> Result

Execute a circuit on the local Aer simulator.

PARAMETER	DESCRIPTION
`circuit`	QuantSDK circuit to run. TYPE: `Circuit`
`shots`	Number of shots (default 1024). TYPE: `int` DEFAULT: `1024`
`**options`	Additional Aer options (seed_simulator, etc.). TYPE: `Any` DEFAULT: `{}`

RETURNS	DESCRIPTION
`Result`	QuantSDK Result with measurement counts.

info ¶

info() -> BackendInfo

Get info about the Aer simulator.

Backend¶

Architecture¶

Core Interfaces¶

Backend ABC¶

Backend ¶

Attributes¶

name property ¶

is_simulator property ¶

Functions¶

run abstractmethod ¶

info abstractmethod ¶

BackendInfo¶

BackendInfo dataclass ¶

BackendStatus¶

BackendStatus ¶

Local Simulator¶

LocalSimulator ¶

Functions¶

run ¶

Usage¶

Limitations¶

IBM Backends¶

IBMBackend ¶

Functions¶

run ¶

info ¶

available_backends ¶

AerBackend ¶

Functions¶

run ¶

info ¶

name `property` ¶

is_simulator `property` ¶

run `abstractmethod` ¶

info `abstractmethod` ¶

BackendInfo `dataclass` ¶