Engines

Engines are the computational backends that perform low-level state operations. MPSTAB uses a modular engine architecture allowing different implementations to be swapped for specific use cases.

Two Engine Types:

1. Stabilizer Engines: Handle Clifford gates efficiently

2. Tensor Network Engines: Manage non-Clifford effects via MPO

Stabilizer Engines

Handle pure stabilizer/Clifford circuit simulation.

class mpstab.engines.stabilizers.native.NativeStabilizersEngine

Bases: StabilizersEngine

backpropagate(observable: str, clifford_circuit: Circuit) → str

Process a given Pauli string by applying the inverse of the circuit gates in reverse order (Heisenberg picture).

Native Stabilizer Engine: - Pure Python implementation - Highest compatibility - Suitable for all Clifford circuits - Can handle hundreds of qubits

Stim-based stabilizers engine.

class mpstab.engines.stabilizers.stim.StimEngine

Bases: StabilizersEngine

Stabilizers engine powered by Stim.

backpropagate(observable: str, clifford_circuit: Circuit) → str

Evolve observable using stim while correctly handling the sign and string padding.

Stim Engine: - Fast, C++-backed stabilizer simulator - Requires Stim library installation - Best for large Clifford circuits - Seamless integration with MPSTAB

Tensor Network Engines

Manage non-Clifford effects through Matrix Product Operator (MPO) representations.

class mpstab.engines.tensor_networks.native.NativeTensorNetworkEngine

Bases: TensorNetworkEngine

Thin adapter that exposes the minimal API required by HybridSurrogate while reusing the existing evolutors.tensor_network implementation.

build_circuit_mps(n: int, initial_state_amplitudes: Any, initial_state_circuit: Any, max_bond_dimension: int | None = None)

Create a CircuitMPS initialised with initial_state. initial_state is passed as-is to CircuitMPS (the caller creates the array of single-qubit amplitudes as before).

expval(state_circuit: CircuitMPS, operator: PauliMPO)

Compute the expectation value of operator on state.

pauli_mpo(pauli_string: str | object)

Return the existing PauliMPO for the given pauli_string.

pauli_rot(state_circuit: CircuitMPS, generator: str, angle: float, max_bond_dimension: int)

Apply a Pauli rotation specified by generator and angle to the MPS.

Native Tensor Network Engine: - Pure Python implementation - Direct control over MPS/MPO operations - Suitable for understanding tensor network mechanics - Good for small to medium systems

class mpstab.engines.tensor_networks.quimb.QuimbEngine(backend: str = 'numpy', cache: bool = False, cache_directory: str | None = 'contractions_cache')

Bases: TensorNetworkEngine

Tensor network engine using Quimb for tensor network manipulations and contractions. The engine supports caching of contraction paths using cotengra’s ReusableOptimizer.

PauliExp(pauli_string, theta)

Returns the MPO for exp(-i * theta/2 * P) where P is a Pauli string. The euler formula is used: exp(-i * theta/2 * P) = cos(theta/2) * I + i * sin(theta/2) * P.

build_circuit_mps(n: int, initial_state_amplitudes: Any, initial_state_circuit: Any, max_bond_dimension: int | None = None)

Builds a Circuit MPS object in Quimb. The underlying tensor network is a Matrix Product State. truncation_fidelity is initialized.

expval(state_circuit: MatrixProductState, operator: MatrixProductOperator)

Compute the expectation value of operator on state_circuit. - state_circuit: MatrixProductState representing the state of the system - operator: MatrixProductOperator representing the observable whose expectation value we want to compute Due to truncation we loose unitary norm, so normalizing is needed when computing expectation.

pauli_mpo(pauli_string: str | object)

Build a Matrix Product Operator (MPO) representing a given Pauli string.

pauli_rot(state_circuit: MatrixProductState, generator: str, angle: float, max_bond_dimension: int)

Apply a Pauli string rotation MPO to an MPS and return the updated object. SVD is performed with compression given by specified bond dimension.

Quimb Engine: - Advanced tensor network library integration - Optimized contraction paths via Cotengra - Excellent for larger systems with manageable bond dimensions - Automatic optimization of tensor operations

Engine Comparison

Engine	Speed	Best For	Max Qubits*
Native Stabilizer	Medium	Clifford only	1000+
Stim	Very Fast	Clifford, large	1000+
Native TN	Moderate	Understanding TN	~20
Quimb	Fast	Mixed circuits	~50

Approximate limits depend on bond dimension and circuit complexity. Performance scales with system size.

Selecting Engines

Engines are automatically selected based on your circuit type and parameters:

from qibo import Circuit, gates
from mpstab import HSMPO
from mpstab.models.ansatze import HardwareEfficient

clifford_circuit = Circuit(nqubits=10)
# Add only Clifford gates
for q in range(10):
     clifford_circuit.add(gates.H(q))
     clifford_circuit.add(gates.CNOT(q0=q%10, q1=(q+1)%10))

# Clifford circuit - uses stabilizer engine only
simulator = HSMPO(ansatz=clifford_circuit)

# Constructing a circuit with also magic gates
mixed_circuit = HardwareEfficient(
     nqubits=10,
     nlayers=3,
)

# Mixed circuit with bond limit - uses both engines
simulator = HSMPO(
    ansatz=mixed_circuit,
    max_bond_dimension=32  # Enables tensor network engine
)

For detailed guidance, see Working with Engines

Engine Interface

All engines implement standardized interfaces for compatibility.

Base Engine Classes:

from mpstab.engines import StabilizersEngine, TensorNetworkEngine

These abstract base classes define the required methods that any engine must implement.

Performance Tuning

Tips for optimal engine performance:

1. Stabilizer Engines: Can handle very large systems efficiently

2. Tensor Network Engines: Performance highly dependent on bond dimension

3. Quimb Engine: Automatic optimization may have startup overhead

4. Native TN Engine: Lower overhead but potentially slower for large systems

See Also

• Working with Engines - Engine selection guide

• A quick introduction to HSMPO - Practical examples