🔌 API Reference: Backends¶
This section documents the backend interfaces — both classical and quantum — that power simulation, execution, and quantum-classical hybrid computation in the Probabilistic Quantum Reasoner.
🧠 Backend Base Classes¶
Abstract Backend Interface¶
probabilistic_quantum_reasoner.backends.simulator.Backend
¶
Bases: ABC
Abstract base class for quantum backends.
Classical Simulator Backend¶
probabilistic_quantum_reasoner.backends.simulator.ClassicalSimulator(max_qubits=20, noise_model=None)
¶
Bases: Backend
Classical simulation backend for quantum operations.
Provides quantum circuit simulation using classical linear algebra operations. Suitable for small to medium-sized quantum circuits.
Initialize classical simulator.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
max_qubits
|
int
|
Maximum number of qubits to simulate |
20
|
noise_model
|
Optional[Any]
|
Optional noise model for realistic simulation |
None
|
apply_unitary(unitary, qubits)
¶
Apply unitary operation to specified qubits.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
unitary
|
ndarray
|
Unitary matrix |
required |
qubits
|
List[int]
|
List of qubit indices to apply operation to |
required |
compute_expectation_value(observable)
¶
Compute expectation value of observable.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
observable
|
ndarray
|
Observable operator matrix |
required |
Returns:
| Type | Description |
|---|---|
float
|
Expectation value ⟨ψ|O|ψ⟩ |
execute_circuit(circuit, shots=1024)
¶
Execute a quantum circuit (simplified interface).
get_backend_info()
¶
Get backend information and statistics.
get_probabilities(qubits=None)
¶
Get measurement probabilities for specified qubits.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
qubits
|
Optional[List[int]]
|
Qubits to get probabilities for (all if None) |
None
|
Returns:
| Type | Description |
|---|---|
Dict[str, float]
|
Dictionary mapping measurement outcomes to probabilities |
get_statevector()
¶
Get current quantum state vector.
initialize_state(n_qubits, initial_state=None)
¶
Initialize quantum state.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_qubits
|
int
|
Number of qubits |
required |
initial_state
|
Optional[ndarray]
|
Initial state vector (defaults to |0...0⟩) |
None
|
measure(qubits=None, shots=1024)
¶
Perform measurement on specified qubits.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
qubits
|
Optional[List[int]]
|
Qubits to measure (all if None) |
None
|
shots
|
int
|
Number of measurement shots |
1024
|
Returns:
| Type | Description |
|---|---|
Dict[str, int]
|
Dictionary mapping measurement outcomes to counts |
reset()
¶
Reset simulator to initial state.
⚛️ Quantum Backends¶
Qiskit Backend¶
probabilistic_quantum_reasoner.backends.qiskit_backend.QiskitBackend(backend_name='aer_simulator', use_runtime=False, api_token=None, hub=None, group=None, project=None)
¶
Bases: Backend
Qiskit backend for IBM Quantum systems.
Provides integration with Qiskit for quantum circuit execution on simulators and real quantum hardware.
Initialize Qiskit backend.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
backend_name
|
str
|
Name of Qiskit backend to use |
'aer_simulator'
|
use_runtime
|
bool
|
Whether to use IBM Runtime service |
False
|
api_token
|
Optional[str]
|
IBM Quantum API token |
None
|
hub
|
Optional[str]
|
IBM Quantum hub |
None
|
group
|
Optional[str]
|
IBM Quantum group |
None
|
project
|
Optional[str]
|
IBM Quantum project |
None
|
add_measurement(circuit, qubits=None)
¶
Add measurement operations to circuit.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
circuit
|
QuantumCircuit
|
Quantum circuit to modify |
required |
qubits
|
Optional[List[int]]
|
Qubits to measure (all if None) |
None
|
apply_pauli_gates(circuit, pauli_string)
¶
Apply Pauli gates according to Pauli string.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
circuit
|
QuantumCircuit
|
Quantum circuit |
required |
pauli_string
|
str
|
String of Pauli operators (e.g., "XYZI") |
required |
apply_unitary_to_circuit(circuit, unitary, qubits)
¶
Apply unitary operator to quantum circuit.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
circuit
|
QuantumCircuit
|
Quantum circuit to modify |
required |
unitary
|
UnitaryOperator
|
Unitary operator to apply |
required |
qubits
|
List[int]
|
Target qubits |
required |
compute_expectation(circuit, observable)
¶
Compute expectation value of observable.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
circuit
|
QuantumCircuit
|
Quantum circuit |
required |
observable
|
Any
|
Observable operator (SparsePauliOp or matrix) |
required |
Returns:
| Type | Description |
|---|---|
float
|
Expectation value |
create_bell_state(qubits)
¶
Create Bell state circuit.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
qubits
|
List[int]
|
Two qubits to entangle |
required |
Returns:
| Type | Description |
|---|---|
QuantumCircuit
|
Quantum circuit creating Bell state |
create_circuit(n_qubits, n_classical=None)
¶
Create a quantum circuit.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_qubits
|
int
|
Number of qubits |
required |
n_classical
|
Optional[int]
|
Number of classical bits (defaults to n_qubits) |
None
|
Returns:
| Type | Description |
|---|---|
QuantumCircuit
|
QuantumCircuit instance |
create_ghz_state(qubits)
¶
Create GHZ state circuit.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
qubits
|
List[int]
|
Qubits to entangle in GHZ state |
required |
Returns:
| Type | Description |
|---|---|
QuantumCircuit
|
Quantum circuit creating GHZ state |
create_quantum_state(amplitudes, basis_labels)
¶
Create QuantumState from amplitudes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
amplitudes
|
ndarray
|
State amplitudes |
required |
basis_labels
|
List[str]
|
Basis state labels |
required |
Returns:
| Type | Description |
|---|---|
QuantumState
|
QuantumState instance |
estimate_runtime(circuit, shots=1024)
¶
Estimate runtime for circuit execution.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
circuit
|
QuantumCircuit
|
Circuit to analyze |
required |
shots
|
int
|
Number of shots |
1024
|
Returns:
| Type | Description |
|---|---|
Dict[str, Any]
|
Runtime estimation information |
execute_circuit(circuit, shots=1024)
¶
Execute quantum circuit and return measurement counts.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
circuit
|
QuantumCircuit
|
Quantum circuit to execute |
required |
shots
|
int
|
Number of measurement shots |
1024
|
Returns:
| Type | Description |
|---|---|
Dict[str, int]
|
Dictionary mapping measurement outcomes to counts |
get_backend_properties()
¶
Get backend properties and capabilities.
get_statevector(circuit)
¶
Get state vector from quantum circuit.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
circuit
|
QuantumCircuit
|
Quantum circuit |
required |
Returns:
| Type | Description |
|---|---|
ndarray
|
State vector as numpy array |
optimize_circuit(circuit, optimization_level=1)
¶
Optimize quantum circuit for the backend.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
circuit
|
QuantumCircuit
|
Circuit to optimize |
required |
optimization_level
|
int
|
Optimization level (0-3) |
1
|
Returns:
| Type | Description |
|---|---|
QuantumCircuit
|
Optimized circuit |
PennyLane Backend¶
probabilistic_quantum_reasoner.backends.pennylane_backend.PennyLaneBackend(device_name='default.qubit', n_qubits=4, shots=None, **device_kwargs)
¶
Bases: Backend
PennyLane backend for quantum machine learning.
Provides integration with PennyLane for variational quantum algorithms, quantum machine learning, and automatic differentiation.
Initialize PennyLane backend.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
device_name
|
str
|
PennyLane device name |
'default.qubit'
|
n_qubits
|
int
|
Number of qubits |
4
|
shots
|
Optional[int]
|
Number of shots (None for exact simulation) |
None
|
**device_kwargs
|
Additional device arguments |
{}
|
apply_unitary_circuit(unitary, qubits, parameters=None)
¶
Create circuit function that applies unitary operator.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
unitary
|
UnitaryOperator
|
Unitary operator to apply |
required |
qubits
|
List[int]
|
Target qubits |
required |
parameters
|
Optional[ndarray]
|
Optional parameters for parametric unitaries |
None
|
Returns:
| Type | Description |
|---|---|
Callable
|
Circuit function |
compute_expectation(circuit_func, observable)
¶
Compute expectation value of observable.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
circuit_func
|
Callable
|
Circuit function |
required |
observable
|
Any
|
Observable (PennyLane observable or matrix) |
required |
Returns:
| Type | Description |
|---|---|
float
|
Expectation value |
compute_gradient(circuit_func, parameters, cost_function=None)
¶
Compute gradient of circuit with respect to parameters.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
circuit_func
|
Callable
|
Parametric circuit function |
required |
parameters
|
ndarray
|
Circuit parameters |
required |
cost_function
|
Optional[Callable]
|
Cost function (defaults to expectation of PauliZ) |
None
|
Returns:
| Type | Description |
|---|---|
ndarray
|
Gradient array |
create_bell_circuit(qubits)
¶
Create Bell state circuit.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
qubits
|
List[int]
|
Two qubits to entangle |
required |
Returns:
| Type | Description |
|---|---|
Callable
|
Bell state circuit function |
create_ghz_circuit(qubits)
¶
Create GHZ state circuit.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
qubits
|
List[int]
|
Qubits to entangle |
required |
Returns:
| Type | Description |
|---|---|
Callable
|
GHZ state circuit function |
create_qnode(circuit_func, name='qnode')
¶
Create a quantum node (QNode) from circuit function.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
circuit_func
|
Callable
|
Circuit function |
required |
name
|
str
|
Name for the QNode |
'qnode'
|
Returns:
| Type | Description |
|---|---|
QNode
|
PennyLane QNode |
create_quantum_neural_network(n_layers=3, input_encoding='angle')
¶
Create quantum neural network circuit.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_layers
|
int
|
Number of layers |
3
|
input_encoding
|
str
|
Input encoding method |
'angle'
|
Returns:
| Type | Description |
|---|---|
Callable
|
QNN circuit function |
create_quantum_state(amplitudes, basis_labels)
¶
Create QuantumState from amplitudes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
amplitudes
|
ndarray
|
State amplitudes |
required |
basis_labels
|
List[str]
|
Basis state labels |
required |
Returns:
| Type | Description |
|---|---|
QuantumState
|
QuantumState instance |
create_variational_circuit(n_layers=3, template='StronglyEntanglingLayers')
¶
Create variational quantum circuit.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_layers
|
int
|
Number of variational layers |
3
|
template
|
str
|
PennyLane template to use |
'StronglyEntanglingLayers'
|
Returns:
| Type | Description |
|---|---|
Callable
|
Variational circuit function |
execute_circuit(circuit_func, shots=1024)
¶
Execute circuit and return measurement counts.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
circuit_func
|
Callable
|
Circuit function to execute |
required |
shots
|
int
|
Number of measurement shots |
1024
|
Returns:
| Type | Description |
|---|---|
Dict[str, int]
|
Dictionary mapping measurement outcomes to counts |
get_device_info()
¶
Get device information and capabilities.
get_statevector(circuit_func)
¶
Get state vector from circuit.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
circuit_func
|
Callable
|
Circuit function |
required |
Returns:
| Type | Description |
|---|---|
ndarray
|
State vector as numpy array |
optimize_circuit(circuit_func, initial_params, cost_function, optimizer='AdamOptimizer', max_iterations=100, learning_rate=0.1)
¶
Optimize circuit parameters.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
circuit_func
|
Callable
|
Parametric circuit function |
required |
initial_params
|
ndarray
|
Initial parameters |
required |
cost_function
|
Callable
|
Cost function to minimize |
required |
optimizer
|
str
|
Optimizer name |
'AdamOptimizer'
|
max_iterations
|
int
|
Maximum optimization iterations |
100
|
learning_rate
|
float
|
Learning rate |
0.1
|
Returns:
| Type | Description |
|---|---|
Dict[str, Any]
|
Optimization results |
prepare_state(target_state)
¶
Create circuit to prepare target quantum state.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
target_state
|
ndarray
|
Target state vector |
required |
Returns:
| Type | Description |
|---|---|
Callable
|
State preparation circuit function |
tensor_network_contraction(tensors)
¶
Perform tensor network contraction (if supported by device).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
tensors
|
List[ndarray]
|
List of tensors to contract |
required |
Returns:
| Type | Description |
|---|---|
ndarray
|
Contracted tensor |
🧪 Noise Modeling¶
Noise Model Base Class¶
probabilistic_quantum_reasoner.backends.simulator.NoiseModel(measurement_error=0.01, gate_error=0.001, decoherence_time=None)
¶
Simple noise model for classical simulation.
Initialize noise model.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
measurement_error
|
float
|
Probability of measurement bit flip |
0.01
|
gate_error
|
float
|
Probability of gate error |
0.001
|
decoherence_time
|
Optional[float]
|
T2 decoherence time (microseconds) |
None
|
apply_gate_noise(state, gate_time=0.1)
¶
Apply gate noise to quantum state.