API Reference

This reference documents the public API: the Executor factory, the shared executor interface, the backend-agnostic building blocks, and each backend plugin.

The Executor factory

Executor is the entry point for creating backend executors. It is a factory and cannot be instantiated directly — use create().

class qc_executor.factory.Executor

Bases: object

Factory class for creating executor instances based on backend name.

This class provides a plugin-based architecture for executor backends. Backends can be registered using the @Executor.register() decorator or discovered automatically via entry points.

Example

>>> executor = Executor.create("qiskit", shots=1024)
>>> backends = Executor.available_backends()
>>> print(backends)  # ['qiskit', 'pennylane', 'qulacs']

classmethod register(name)

Decorator to register a backend implementation.

Parameters:

name (str) – The name of the backend (e.g., “qiskit”, “pennylane”, “qulacs”)

Return type:

Callable[[Type[ExecutorBase]], Type[ExecutorBase]]

Returns:

Decorator function that registers the backend class

Raises:

TypeError – If the decorated class does not inherit from ExecutorBase

Example

>>> @Executor.register("qiskit")
... class QiskitExecutor(ExecutorBase):
...     pass

classmethod create(target, **kwargs)

Create an executor instance for the specified backend.

Parameters:

• target (str | Any) – Name of the backend (e.g., “qiskit”, “pennylane”, “qulacs”). May also be a Qiskit Backend / BackendV2 instance, in which case the "qiskit" executor is used automatically and the object is forwarded as backend=<instance>.

• **kwargs – Configuration parameters passed to the backend constructor

Return type:

ExecutorBase

Returns:

An instance of the requested backend executor

Raises:

ValueError – If the backend is not found or not installed

Example

>>> executor = Executor.create("qiskit", shots=1024, seed=42)
>>> executor = Executor.create("pennylane", shots=1000)

classmethod available_backends()

Get a list of available (installed) backends.

Return type:

list[str]

Returns:

List of backend names that can be used with create()

Example

>>> backends = Executor.available_backends()
>>> print(backends)  # ['qiskit', 'pennylane', 'qulacs']

classmethod switch_backend(executor, backend, **overrides)

Switch an executor to a different backend while preserving its configuration.

Creates a new executor instance with the specified backend, copying the current configuration and applying any overrides.

Parameters:

• executor (ExecutorBase) – The existing executor whose configuration should be copied.

• backend (str | Any) – Name of the backend to switch to (e.g., "qiskit", "pennylane", "qulacs"). May also be a Qiskit Backend / BackendV2 instance, in which case the "qiskit" executor is used automatically.

• **overrides – Configuration parameters to override (e.g., shots=2048)

Returns:

New executor instance with the specified backend

Return type:

ExecutorBase

Example

>>> executor = Executor.create("qiskit", shots=1024, seed=42)
>>> pennylane_executor = Executor.switch_backend(executor, "pennylane")
>>> # pennylane_executor has shots=1024, seed=42
>>>
>>> # Override specific parameters
>>> qulacs_executor = Executor.switch_backend(executor, "qulacs", shots=2048)
>>> # qulacs_executor has shots=2048, seed=42
>>>
>>> # Switch to a real IBM Quantum backend
>>> from qiskit_ibm_runtime import QiskitRuntimeService
>>> service = QiskitRuntimeService()
>>> ibm_backend = service.least_busy(operational=True, simulator=False)
>>> ibm_executor = Executor.switch_backend(executor, ibm_backend)

Shared executor interface

All backend executors inherit from ExecutorBase, which defines the common configuration options (passed through Executor.create) and the evaluation interface shared by every backend.

class qc_executor.base.executor_base.ExecutorBase(backend=None, shots=None, seed=None, log_file=None, log_level='WARNING', caching=None, cache_dir='cache', max_cache_size=None)

Bases: ABC

Base class for quantum circuit executors.

Parameters:

• 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 (for example "DEBUG", "INFO", "WARNING", "ERROR").

• caching (bool | None, optional) – Whether to cache computation results in memory.

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

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

• backend (Any)

property shots: int | None

Return the number of shots.

property remote: bool

Return True if the execution access a remote backend.

get_config()

Get the current executor configuration.

Returns:

Dictionary containing the executor configuration parameters

(shots, seed, log_file, log_level, caching, cache_dir, max_cache_size)

Return type:

dict

Example

>>> executor = Executor.create("qiskit", shots=1024, seed=42)
>>> config = executor.get_config()
>>> print(config)  # {'shots': 1024, 'seed': 42, ...}

switch_backend(backend, **overrides)

Switch to a different backend while preserving configuration.

Delegates to Executor.switch_backend.

Parameters:

• backend (Any) – Name of the backend (e.g., "qiskit", "pennylane") or a backend instance for auto-detection.

• **overrides – Configuration parameters to override (e.g., shots=2048)

Returns:

New executor instance with the specified backend

Return type:

ExecutorBase

expectation_value(circuit, observable, **parameters)

Calculate the expectation value of the observable with respect to the circuit.

Parameters:

• circuit (QuantumCircuitBase | List[QuantumCircuitBase]) – The quantum circuit or a list of circuits.

• observable (QuantumOperatorBase | List[QuantumOperatorBase]) – The quantum observable or a list of observables.

• parameters – Additional values for the free parameters of the circuit(s) and the observable(s) given as keyword arguments. Both vector-style keys (e.g., x=[0.1, 0.2]) and indexed keys (e.g., x[0]=0.1, x[1]=0.2) are accepted and normalized.

Returns:

The expectation value either as a single float or as a

numpy array if multiple circuits/observables are provided.

Return type:

float | np.array

expectation_value_derivatives(circuit, observable, *derivative, **parameters)

Calculate the derivatives of the expectation value with respect to the parameters of the circuit.

Parameters:

• circuit (QuantumCircuitBase | List[QuantumCircuitBase]) – The quantum circuit or a list of circuits.

• observable (QuantumOperatorBase | List[QuantumOperatorBase]) – The quantum observable or a list of observables.

• derivative – The parameter(s) with respect to which the derivative is calculated.

• parameters – Additional values for the free parameters of the circuit(s) and the observable(s) given as keyword arguments. Both vector-style keys (e.g., x=[0.1, 0.2]) and indexed keys (e.g., x[0]=0.1, x[1]=0.2) are accepted and normalized.

Returns:

The derivative of the expectation value:

• single float/array if one derivative parameter is requested

• dictionary mapping parameter names to gradient arrays if multiple parameters are requested

Return type:

float | np.array | dict

sample(circuit, **parameters)

Computes samples of the quantumstate of the given circuit.

Parameters:

• circuit (QuantumCircuitBase | List[QuantumCircuitBase]) – The quantum circuit or a list of circuits.

• parameters – Additional values for the free parameters of the circuit(s) given as keyword arguments. Both vector-style keys (e.g., x=[0.1, 0.2]) and indexed keys (e.g., x[0]=0.1, x[1]=0.2) are accepted and normalized.

Returns:

The sampled results either as a single dictionary or a

list of dictionaries if multiple circuits are provided.

Return type:

dict | List[dict]

statevector(circuit, **parameters)

Computes the statevector of the quantum circuit.

Parameters:

• circuit (QuantumCircuitBase | List[QuantumCircuitBase]) – The quantum circuit or a list of circuits.

• parameters – Additional values for the free parameters of the circuit(s) given as keyword arguments. Both vector-style keys (e.g., x=[0.1, 0.2]) and indexed keys (e.g., x[0]=0.1, x[1]=0.2) are accepted and normalized.

Returns:

The statevector of the circuit(s).

Return type:

np.ndarray

transpile_circuit(circuit)

Transpile the circuit for execution on this executor’s backend.

Subclasses may override _transpile_circuit() to apply backend-specific optimisations (e.g. gate decomposition, qubit routing). When a list of circuits is provided, each circuit is transpiled and cached individually.

Parameters:

circuit (QuantumCircuitBase | List[QuantumCircuitBase]) – The quantum circuit or a list of circuits to transpile.

Returns:

The transpiled

circuit(s).

Return type:

QuantumCircuitBase | List[QuantumCircuitBase]

transpile_operator(operator)

Overloads:

• self, operator (QuantumOperatorBase) → QuantumOperatorBase

• self, operator (List[QuantumOperatorBase]) → List[QuantumOperatorBase]

Parameters:

operator (QuantumOperatorBase | List[QuantumOperatorBase])

Return type:

QuantumOperatorBase | List[QuantumOperatorBase]

Transpile the operator for execution on this executor’s backend.

Subclasses may override _transpile_operator() to apply backend-specific conversions (e.g., to wrapper types). When a list of operators is provided, each operator is transpiled and cached individually.

Parameters:

operator (QuantumOperatorBase | List[QuantumOperatorBase]) – The quantum operator or a list of operators to transpile.

Returns:

The transpiled

operator(s).

Return type:

QuantumOperatorBase | List[QuantumOperatorBase]

abstractmethod classmethod get_accepted_backend_types()

Return a list of backend object types accepted by this executor.

This is used for auto-detection when a non-string backend is passed to Executor.create(). If the backend object is an instance of any of the returned types, this executor will be selected automatically.

Returns:

List of accepted backend types

(e.g., Qiskit Backend / BackendV2 classes)

Return type:

List[type]

classmethod get_accepted_backend_aliases()

Return string aliases accepted by this executor.

This optional list is used by Executor.create() when a string target is not a registered backend name. The factory resolves aliases to the owning plugin and forwards the original string via backend=<target>.

Returns:

String aliases accepted by the executor.

Return type:

List[str]

Core building blocks

Backend-agnostic circuit, observable, and parameter types from the package root.

class qc_executor.quantum_circuit.QuantumCircuit(num_qubits, _native_circuit=None)

Bases: QuantumCircuitBase

Base class for quantum circuits for different quantum frameworks.

Parameters:

• num_qubits (int) – Number of qubits in the circuit

• _native_circuit (QiskitQuantumCircuit | None)

classmethod from_quantum_circuit(circuit)

Identity conversion for generic circuits.

Return type:

QuantumCircuitBase

Parameters:

circuit (QuantumCircuitBase)

property qiskit_circuit: QuantumCircuit

The underlying Qiskit circuit.

property num_qubits: int

Return the number of qubits in the circuit.

property parameters: List[ParameterVectorElement]

Return the free trainable parameters in the circuit.

property num_parameters: int

Return the number of free trainable parameters in the circuit.

property is_parameterized: bool

Check if the wavefunction is parameterized.

draw()

Returns printable string representation of the circuit.

Return type:

str

h(qubits)

Add hadamard gates

Parameters:

qubits (int | List[int])

s(qubits)

Add S gates

Parameters:

qubits (int | List[int])

sdag(qubits)

Add Sdag gates

Parameters:

qubits (int | List[int])

t(qubits)

Add T gates

Parameters:

qubits (int | List[int])

tdag(qubits)

Add Tdg gates

Parameters:

qubits (int | List[int])

p(qubits, angle)

Add P gates

Parameters:

• qubits (int | List[int])

• angle (float)

cp(control_qubit, target_qubit, angle)

Add CP gates

Parameters:

• control_qubit (int)

• target_qubit (int)

• angle (float)

x(qubits)

Add X gates

Parameters:

qubits (int | List[int])

y(qubits)

Add Y gates

Parameters:

qubits (int | List[int])

z(qubits)

Add Z gates

Parameters:

qubits (int | List[int])

rx(qubits, angle)

Add RX gates

Parameters:

• qubits (int | List[int])

• angle (float)

ry(qubits, angle)

Add RY gates

Parameters:

• qubits (int | List[int])

• angle (float)

rz(qubits, angle)

Add RZ gates

Parameters:

• qubits (int | List[int])

• angle (float)

cx(control_qubit, target_qubit)

Add CNOT gates

Parameters:

• control_qubit (int)

• target_qubit (int)

cy(control_qubit, target_qubit)

Add CY gates

Parameters:

• control_qubit (int)

• target_qubit (int)

cz(control_qubit, target_qubit)

Add CZ gates

Parameters:

• control_qubit (int)

• target_qubit (int)

cnot(control_qubit, target_qubit)

Add CNOT gates

Parameters:

• control_qubit (int)

• target_qubit (int)

ccx(control_qubit1, control_qubit2, target_qubit)

Add Toffoli (CCX) gates

Parameters:

• control_qubit1 (int)

• control_qubit2 (int)

• target_qubit (int)

toffoli(control_qubit1, control_qubit2, target_qubit)

Add Toffoli (CCX) gates

Parameters:

• control_qubit1 (int)

• control_qubit2 (int)

• target_qubit (int)

ecr(control_qubit, target_qubit)

Add ECR gates

Parameters:

• control_qubit (int)

• target_qubit (int)

crx(control_qubit, target_qubit, angle)

Add CRX gates

Parameters:

• control_qubit (int)

• target_qubit (int)

• angle (float)

cry(control_qubit, target_qubit, angle)

Add CRY gates

Parameters:

• control_qubit (int)

• target_qubit (int)

• angle (float)

crz(control_qubit, target_qubit, angle)

Add CRZ gates

Parameters:

• control_qubit (int)

• target_qubit (int)

• angle (float)

rxx(control_qubit, target_qubit, angle)

Add RXX gates

Parameters:

• control_qubit (int)

• target_qubit (int)

• angle (float)

ryy(control_qubit, target_qubit, angle)

Add RYY gates

Parameters:

• control_qubit (int)

• target_qubit (int)

• angle (float)

rzz(control_qubit, target_qubit, angle)

Add RZZ gates

Parameters:

• control_qubit (int)

• target_qubit (int)

• angle (float)

rzx(control_qubit, target_qubit, angle)

Add RZX gates

Parameters:

• control_qubit (int)

• target_qubit (int)

• angle (float)

swap(qubit1, qubit2)

Add SWAP gates

Parameters:

• qubit1 (int)

• qubit2 (int)

barrier(qubits)

Add barrier gates

Parameters:

qubits (int | List[int])

measure()

Add measure gates

compose(qc, qubits)

Compose two quantum circuits.

Return type:

QuantumCircuit

Parameters:

• qc (QuantumCircuitBase)

• qubits (List[int])

assign_parameters(parameters)

Change parameters in the circuit.

Parameters:

parameters (np.array) – parameters to assign to the circuit

invert()

Invert the circuit.

Return type:

QuantumCircuit

copy()

Return a copy of the circuit.

Return type:

QuantumCircuit

circuit_metrics()

count number of gates in the circuit

Return type:

dict

from_qasm(qasm)

Load the circuit from a qasm string

Return type:

None

Parameters:

qasm (str)

to_qasm()

Convert the circuit to a qasm string

Return type:

str

class qc_executor.quantum_operator.QuantumOperator(paulis=None, coeffs=None, num_qubits=None, _native_operator=None)

Bases: QuantumOperatorBase

Quantum operator backed by a Qiskit SparsePauliOp.

Parameters:

• paulis (Optional[List[str]])

• coeffs (Optional[List[float]])

• num_qubits (Optional[int])

• _native_operator (Optional[SparsePauliOp])

classmethod from_quantum_operator(operator)

Identity conversion for generic operators.

Return type:

QuantumOperatorBase

Parameters:

operator (QuantumOperatorBase)

property qiskit_operator: SparsePauliOp

The underlying Qiskit SparsePauliOp.

property num_qubits: int

Return the number of qubits in the circuit.

property num_paulis: int

Return the number of Paulis in the operator.

property paulis: List[str]

Return the list of Paulis.

property coeffs: List

Return the list of coefficients.

property is_parametrized: bool

Return True if the operator is parametrized.

property parameters: list

Return the parameters of the operator.

Returns:

List of parameters.

property num_parameters: int

Return the number of parameters in the operator.

Returns:

Number of parameters.

copy()

Return a copy of the operator.

Return type:

QuantumOperatorBase

Returns:

Copy of the operator.

adjoint()

Return the adjoint of the operator.

Return type:

QuantumOperatorBase

Returns:

Adjoint of the operator.

apply_layout(layout)

Apply a layout to the operator.

Parameters:

layout (List[int]) – Layout to apply.

Return type:

QuantumOperatorBase

Returns:

Operator with applied layout.

compose(other)

Compose the operator with another operator.

Parameters:

other (QuantumOperatorBase) – Operator to compose with.

Return type:

QuantumOperatorBase

Returns:

Composed operator.

append(pauli, coeff=None)

Append a Pauli operator with a coefficient to the operator.

Parameters:

• pauli (str) – Pauli operator to append.

• coeff (float) – Coefficient of the Pauli operator.

Return type:

QuantumOperatorBase

simplify()

Simplify the operator.

Return type:

QuantumOperatorBase

Returns:

Simplified operator.

transpose()

Return the transpose of the operator.

Return type:

QuantumOperatorBase

Returns:

Transpose of the operator.

conjugate()

Return the conjugate of the operator.

Return type:

QuantumOperatorBase

Returns:

Conjugate of the operator.

group_commuting()

Group commuting operators.

Return type:

List[QuantumOperatorBase]

Returns:

List of commuting operators.

property is_unitary: bool

Return True if the operator is unitary.

Returns:

True if the operator is unitary.

property is_real: bool

Return True if the operator is real.

Returns:

True if the operator is real.

property is_imaginary: bool

Return True if the operator is imaginary.

Returns:

True if the operator is imaginary.

qc_executor.parameters.Parameters

alias of ParameterVector

Backend plugins

Each plugin provides an executor plus native circuit/operator wrappers. You normally obtain an executor through Executor.create("<name>") rather than instantiating these classes directly, but their public classes are documented on the per-plugin pages below.

qc_executor.qiskit	Qiskit backend for the executor framework.
qc_executor.pennylane	PennyLane backend for Executor.
qc_executor.qulacs	Qulacs backend for Executor.
qc_executor.pauli_propagation	Pauli Propagation Package for Quantum Computing.