MaestroConfig

class MaestroConfig(simulator_type=None, simulation_type=None, max_bond_dimension=None, singular_value_threshold=None, use_double_precision=False, disable_optimized_swapping=False, lookahead_depth=-1, mps_measure_no_collapse=True, mps_qubit_threshold=22, noise_model=None, noise_seed=42, noise_realizations=None)

Bases: object

Configuration object for MaestroSimulator.

Each field maps directly to an identically-named field on maestro.SimulatorConfig; see the maestro Python bindings guide for the underlying semantics of each knob. mps_qubit_threshold is Divi-specific and drives automatic Statevector → MatrixProductState selection.

simulator_type and simulation_type accept the string names of the corresponding maestro enum members, e.g. "QCSim", "Gpu", "Statevector", "MatrixProductState". None means “use maestro’s default”.

Every field is explicit — unknown options raise TypeError at construction time instead of being silently dropped by a **kwargs passthrough, so upstream changes to maestro.SimulatorConfig surface as loud failures.

Attributes Summary

disable_optimized_swapping	Disable MPS swap-cost optimization.
lookahead_depth	Lookahead depth for the MPS swap optimizer.
max_bond_dimension	Maximum bond dimension for MPS simulation.
mps_measure_no_collapse	If True, use the non-collapsing MPS measurement algorithm; if False, use the collapsing one.
mps_qubit_threshold	Qubit count above which automatic MPS selection kicks in.
noise_model	Maestro NoiseModel object.
noise_realizations	Number of Monte-Carlo noise realizations.
noise_seed	Seed for Pauli-error sampling.
simulation_type	Simulation method, e.g. "Statevector" or "MatrixProductState".
simulator_type	Maestro simulator type, e.g. "QCSim" or "Gpu".
singular_value_threshold	SVD truncation threshold for MPS simulation.
use_double_precision	Use double-precision floating point.

Methods Summary

override(other)

Return a new config overriding fields with non-default values from other.

Attributes Documentation

disable_optimized_swapping: bool = False

Disable MPS swap-cost optimization.

lookahead_depth: int = -1

Lookahead depth for the MPS swap optimizer. -1 is maestro’s default.

max_bond_dimension: int | None = None

Maximum bond dimension for MPS simulation. None uses maestro’s default, except when auto-MPS is triggered (in which case 64 is used).

mps_measure_no_collapse: bool = True

If True, use the non-collapsing MPS measurement algorithm; if False, use the collapsing one.

mps_qubit_threshold: int = 22

Qubit count above which automatic MPS selection kicks in. Only active when simulation_type is None; has no effect when simulation_type is set explicitly. Divi-specific; not forwarded to maestro.SimulatorConfig.

noise_model: NoiseModel | None = None

Maestro NoiseModel object. None (default) disables noise — circuits run via simple_execute (sampling) or simple_estimate (expval). When set, dispatch routes to noisy_execute / noisy_estimate / noisy_estimate_montecarlo depending on noise_realizations. Divi-specific; not forwarded to maestro.SimulatorConfig — Maestro keeps noise models separate from simulator config and accepts them positionally on the noisy entry points.

noise_realizations: int | None = None

Number of Monte-Carlo noise realizations. None (default) selects the analytical noisy backend when available:

• Expval — maestro.noisy_estimate, which applies exact Pauli damping coefficients to noiseless expectation values. Deterministic.

• Sampling — no analytical equivalent; falls back to one realization (noisy_execute with noise_realizations=1).

A positive int N selects Monte-Carlo backends:

• Expval — maestro.noisy_estimate_montecarlo, which runs N independent Pauli-injection passes and averages the expectation values.

• Sampling — maestro.noisy_execute, which divides shots across min(shots, N) batches, each with a freshly sampled noise pattern. Total shot count is always shots; if N > shots the effective realization count is capped at shots.

Note that noise_realizations=1 is not equivalent to None for expval — the former is one random Pauli sampling, the latter is the exact analytical average. Divi-specific; not forwarded to maestro.SimulatorConfig.

noise_seed: int = 42

Seed for Pauli-error sampling. Consulted whenever execution routes through one of Maestro’s stochastic noisy entry points (noisy_execute or noisy_estimate_montecarlo); the analytical noisy_estimate path ignores it. Each circuit in a MaestroSimulator.submit_circuits() batch is seeded with noise_seed + i (where i is the circuit’s index in the input mapping) so circuits in the same batch get independent error patterns.

Reproducibility scope: the seed pins the Pauli error patterns sampled from the noise model. Expectation-value runs (noisy_estimate_montecarlo) are fully reproducible because the inner loop is analytical. Noisy sampling runs (noisy_execute) are only partially reproducible: the same Pauli errors are injected, but the shot-count outcomes still vary across runs because Maestro’s measurement sampler initialises its own RNG from system entropy on every call.

Divi-specific; not forwarded to maestro.SimulatorConfig.

simulation_type: str | None = None

Simulation method, e.g. "Statevector" or "MatrixProductState". None enables automatic selection based on qubit count.

simulator_type: str | None = None

Maestro simulator type, e.g. "QCSim" or "Gpu". None uses maestro’s default ("QCSim").

singular_value_threshold: float | None = None

SVD truncation threshold for MPS simulation. None uses maestro’s default.

use_double_precision: bool = False

Use double-precision floating point.

Methods Documentation

override(other)

Return a new config overriding fields with non-default values from other.

“Non-default” here means a field whose value differs from the class default. This keeps the override semantics consistent with ExecutionConfig.

Return type:

MaestroConfig