MaestroSimulator

class MaestroSimulator(shots=5000, config=None, track_depth=False)

Bases: CircuitRunner

A CircuitRunner backend powered by qoro-maestro, Qoro’s C++ quantum simulator.

Supports multiple simulation methods (Statevector, MPS, Stabilizer, TensorNetwork, PauliPropagator), intelligent auto-routing, GPU acceleration, and native observable estimation.

All maestro-level configuration — including noise — is carried in a MaestroConfig object rather than as loose keyword arguments, matching the ExecutionConfig / QoroService pattern. Pass a maestro.NoiseModel via MaestroConfig.noise_model (and tune MaestroConfig.noise_seed and MaestroConfig.noise_realizations) to route execution through Maestro’s noisy entry points.

Note

Maestro’s C++ extension must be loaded before other C++ libraries (Qiskit, PennyLane) to avoid initialization order conflicts. This is handled automatically by divi/__init__.py.

Parameters:

• shots (int) – Number of measurement shots. Defaults to 5000.

• config (MaestroConfig | None) – MaestroConfig controlling simulator backend, simulation method, bond dimension, noise model, and related knobs. Defaults to MaestroConfig().

• track_depth (bool) – Record circuit depth per submission. Defaults to False.

Attributes Summary

is_async	Maestro executes circuits synchronously.
supports_expval	Maestro supports native observable estimation.

Methods Summary

close()	Shut down the per-instance executor.
set_seed(seed)	No-op — maestro does not yet expose seeding from C++.
submit_circuits(circuits, *[, ham_ops, ...])	Submit quantum circuits for execution on the maestro simulator.

Attributes Documentation

is_async

Maestro executes circuits synchronously.

supports_expval

Maestro supports native observable estimation.

Methods Documentation

close()

Shut down the per-instance executor.

Safe to call multiple times. Called automatically when the instance is garbage-collected via weakref.finalize, but callers that want deterministic cleanup (e.g. inside long-running services) can invoke this explicitly.

shutdown(wait=True) runs outside _executor_lock — a concurrent submit_circuits on another thread can grab the lock and lazily re-create a fresh pool while the old one drains, instead of serializing behind a slow shutdown. Subsequent submits therefore observe close() as “release current pool; new pool created on demand”.

Return type:

None

set_seed(seed)

No-op — maestro does not yet expose seeding from C++.

Return type:

None

submit_circuits(circuits, *, ham_ops=None, circuit_ham_map=None, shot_groups=None, cancellation_event=None, **kwargs)

Submit quantum circuits for execution on the maestro simulator.

Parameters:

• circuits (Mapping[str, str]) – Dictionary mapping circuit labels to OpenQASM string representations.

• ham_ops (str | None) – Semicolon-separated Pauli string for expectation value estimation, e.g. "ZI;IZ;XX". If None, runs in sampling mode.

• circuit_ham_map (list[list[int]] | None) – Maps circuit index ranges to observable groups for heterogeneous batches. Each inner list contains circuit indices belonging to that observable group.

• shot_groups (list[list[int]] | None) – Per-circuit shot allocation as [start, end, shots] triples covering the iteration order of circuits. Sampling mode only — ignored when ham_ops is provided because maestro’s simple_estimate computes expectation values analytically.

• cancellation_event (Event | None) – When set, aborts further dispatch and raises ExecutionCancelledError. Workers already in maestro’s native call are not interrupted.

• **kwargs – Ignored — accepted so callers using the generic CircuitRunner interface can forward unrelated options without breaking.

Return type:

ExecutionResult

Returns:

ExecutionResult containing either counts (sampling) or expectation values.