qiskit

Dependencies

Install with pip install qc-executor[qiskit-full]. Requires:

• qiskit>=1.0.0

• qiskit-aer>=0.12.0

• qiskit-ibm-runtime>=0.18.0

Executor

class qc_executor.qiskit.QiskitExecutor(backend='statevector', shots=None, seed=None, log_file=None, log_level='WARNING', caching=None, cache_dir='cache', max_cache_size=None, execution_mode='job', options=None)

Bases: ExecutorBase

Class for executing Qiskit circuits.

Supports local simulation ("statevector", "aer") and execution on real IBM Quantum hardware or noise-aware fake backends via qiskit-ibm-runtime.

The backend parameter is the single entry point and accepts all supported configurations:

• "statevector" / "aer" — local simulation string shortcuts.

• A Backend / BackendV2 instance (e.g. from QiskitRuntimeService or fake_provider).

• A qiskit_ibm_runtime.Session or Batch — ownership is transferred to the executor, which closes it on exit.

• A pre-configured Qiskit primitive (BaseSamplerV2 / BaseEstimatorV2 or their V1 equivalents) — injected directly; the missing counterpart primitive is created automatically when possible.

Context-manager use is strongly recommended for real IBM backends to guarantee that sessions are properly closed:

with QiskitExecutor(backend=ibm_backend, execution_mode="session") as exe:
    result = exe.expectation_value(circuit, observable, theta=params)

Parameters:

• backend (str | Backend | Session | Batch | BaseEstimatorV1 | BaseSamplerV1 | BaseEstimatorV2 | BaseSamplerV2) – Backend to use for execution. Accepts: "statevector" (default) or "aer" string shortcuts, a Qiskit Backend instance (IBM hardware or fake), a qiskit_ibm_runtime.Session / Batch, or a pre-configured Qiskit primitive (BaseSamplerV1/V2 / BaseEstimatorV1/V2).

• shots (int | None, optional) – Number of shots for sampling.

• seed (int | None, optional) – Random seed for reproducibility.

• log_file (str | None, optional) – Path to the log file.

• log_level (str, optional) – Logging level.

• caching (bool | None, optional) – Whether to use in-memory caching.

• cache_dir (str, optional) – Directory for caching.

• max_cache_size (int | None, optional) – Maximum number of entries kept in each in-memory cache.

• execution_mode (str, optional) – "job" (default), "session", or "batch". Only relevant for real IBM Quantum backends. Use "session" for iterative algorithms (VQE, QAOA) and "batch" for independent parallel jobs.

• options (dict | None, optional) – Options forwarded to IBM Runtime primitives (e.g. {"resilience_level": 1}). Ignored for local backends.

property shots: int | None

Return the number of shots.

property remote: bool

Return True if the executor targets a remote backend.

property ibm_quantum: bool

Return True if the executor targets a real IBM Quantum device.

property session

Return the active runtime Session or Batch, or None.

close_session()

Close the current runtime session/batch if one is active.

Session ownership is always managed by the executor, including injected Session / Batch objects.

Return type:

None

classmethod get_accepted_backend_types()

Return all types accepted as the backend argument.

Covers: * Qiskit local backends (Backend / BackendV2) * Qiskit statevector primitives (StatevectorEstimator, StatevectorSampler) * Qiskit local primitive base classes (V1 and V2) * IBM Runtime Session / Batch (when qiskit-ibm-runtime is installed) * IBM Runtime primitive classes (V1 and V2, version-gated)

Dummy sentinel classes defined when optional dependencies are absent are intentionally excluded so that isinstance checks never yield false positives.

Return type:

list[type]

classmethod get_accepted_backend_aliases()

Return string aliases accepted by this executor in Executor.create.

Return type:

list[str]

Native abstraction

Circuit

class qc_executor.qiskit.QiskitCircuit(circuit)

Bases: object

Wrapper for Qiskit circuits used by QiskitExecutor. Provides parameter management and circuit caching functionality.

classmethod from_quantum_circuit(circuit)

Create a native Qiskit circuit wrapper from a generic circuit.

property num_qubits: int

Number of qubits in the circuit.

property hash: int

Hash of the circuit for caching.

property parameter_names: List[str]

List of parameter vector names.

property parameter_dimensions: dict

Dictionary mapping parameter names to their dimensions.

property qiskit_circuit

Access to the underlying Qiskit circuit.

property free_parameters: set

Set of all free parameters in the circuit.

bind_parameters(parameter_values)

Bind parameter values to the circuit.

Parameters:

parameter_values (dict) – Dictionary mapping parameter names to values

Returns:

Bound Qiskit circuit

classmethod from_qiskit(qiskit_circuit)

Create a QiskitCircuit directly from a Qiskit QuantumCircuit.

This bypasses the normal __init__ path which expects an executor QuantumCircuit wrapper and instead accepts an already-transpiled Qiskit circuit.

Return type:

QiskitCircuit

copy()

Return a copy of the circuit wrapper.

Operator

class qc_executor.qiskit.QiskitOperator(operator)

Bases: object

Wrapper for Qiskit operators (SparsePauliOp) used by QiskitExecutor. Handles parameter management for parametrized operators.

classmethod from_quantum_operator(operator)

Create a native Qiskit operator wrapper from a generic operator.

property num_qubits: int

Number of qubits the operator acts on.

property hash: int

Hash of the operator for caching.

property parameter_names: List[str]

List of parameter vector names.

property parameter_dimensions: dict

Dictionary mapping parameter names to their dimensions.

property qiskit_operator

Access to the underlying Qiskit SparsePauliOp.

property free_parameters: set

Set of all free parameters in the operator.

bind_parameters(parameter_values)

Bind parameter values to the operator.

Parameters:

parameter_values (dict) – Dictionary mapping parameter names to values

Returns:

Bound Qiskit SparsePauliOp

copy()

Return a copy of the operator wrapper.