Working with Engines

MPSTAB supports multiple computational backends (engines) for different simulation scenarios.

Once an HSMPO is defined, the engines can be customized using the hsmpo.set_engines method. By default we set Stim and Quimb respectively for stabilizers and tensor network simulations:

from mpstab import HSMPO
from qibo import Circuit, gates

circuit = Circuit(3)
circuit.add(gates.H(0))
circuit.add(gates.CNOT(0, 1))

simulator = HSMPO(ansatz=circuit)
# Here we can pass the desired engines
simulator.set_engines()

Available Engines

Stabilizer Engines

Engines that handle the Clifford (stabilizer) part of the circuit:

Stim Engine

  • Speed: State-of-art Clifford simulator

  • Coverage: Pure Clifford circuits

  • Best for: High-performance stabilizer simulation

  • External library: Stim

from mpstab import HSMPO
from qibo import Circuit, gates

circuit = Circuit(5)
circuit.add(gates.H(0))
circuit.add(gates.CNOT(0, 1))

simulator = HSMPO(ansatz=circuit)
# By default we use Stim
Native Stabilizer Engine

  • Speed: Lightweight, fast on single thread CPU

  • Coverage: Pure Clifford circuits only

  • Best for: Large Clifford circuits (thousands of qubits)

  • Implementation: In-house Clifford simulator

from mpstab import HSMPO
from mpstab.engines import NativeStabilizersEngine
from qibo import Circuit, gates

circuit = Circuit(5)
circuit.add(gates.H(0))

simulator = HSMPO(ansatz=circuit)
simulator.set_engines(stab_engine=NativeStabilizersEngine())

Tensor Network Engines

Engines that handle the non-Clifford effects via MPO:

Quimb Engine

  • Speed: Fast (optimized contractions)

  • Memory: Efficient for large bond dimensions

  • Best for: Large systems with moderate bond dimensions

  • Features: Automatic contraction path optimization

  • External library: Quimb

from mpstab import HSMPO
from qibo import Circuit, gates

circuit = Circuit(5)
circuit.add(gates.H(0))
circuit.add(gates.RY(0, theta=0.5))

simulator = HSMPO(ansatz=circuit, max_bond_dimension=32)
# Uses Quimb tensor network engine by default
Native Tensor Network Engine

  • Speed: Moderate

  • Memory: Scales with bond dimension

  • Best for: Small systems with fine controlled network structure

Engine Configuration

from mpstab import HSMPO
from mpstab.models.ansatze import HardwareEfficient

# Define an ansatz or a Qibo circuit
ansatz = HardwareEfficient(nqubits=10, nlayers=3)

# Basic HSMPO with automatic engine selection
simulator = HSMPO(
    ansatz=ansatz,
    max_bond_dimension=32
)

# Access engine information
simulator.set_engines()  # Configure engines
print(f"Stabilizer engine: {simulator.stab_engine}")
print(f"TN engine: {simulator.tn_engine}")

Tips for Efficient Simulation

  1. Use Clifford circuits when possible - they’re orders of magnitude faster

  2. Start with low bond dimensions - increase only if accuracy is insufficient

  3. Profile your circuits - understand what gates are expensive

Example: Adaptive Bond Dimension

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

# Define an ansatz or a Qibo circuit
ansatz = HardwareEfficient(nqubits=10, nlayers=3)

# Start with low bond dimension
for max_bd in [2, 4, 8, 16, 32]:
    simulator = HSMPO(ansatz=ansatz, max_bond_dimension=max_bd)
    result, fidelity = simulator.expectation("Z" * 10, return_fidelity=True)

    print(f"χ_max={max_bd}: result={result:.4f}, fidelity={fidelity:.4f}")

    # Stop if accuracy is sufficient
    if fidelity > 0.99:
        break

Further Reading