Configuration

SimulatorConfig bundles every simulator option into one reusable value. Every execution and estimation function takes one as config; without it, a default SimulatorConfig() runs QCSim with a statevector.

import maestro

config = maestro.SimulatorConfig(
    simulation_type=maestro.SimulationType.MatrixProductState,
    max_bond_dimension=64,
)
config.seed = 7  # fields can also be set after construction
print(config.simulation_type, config.max_bond_dimension, config.seed)

SimulationType.MatrixProductState 64 7

The constructor takes every option by keyword only. The options you’ll actually set lists the handful most people set.

All SimulatorConfig options

Option	Type	Default	Description
simulator_type	SimulatorType	QCSim	Simulation backend. Gpu, DistributedGpu and DistributedMpiGpu require GPU access; see Get GPU access.
simulation_type	SimulationType	Statevector	Simulation method
max_bond_dimension	int or None	None	Bond dimension limit for MPS, MPO and GPU tensor networks. For GPU MPS/MPO, None uses 128. Other backends keep their own defaults.
singular_value_threshold	float or None	None	Truncation threshold for MPS, MPO and GPU tensor networks, read according to truncation_mode
truncation_mode	str or None	None ("discarded_weight")	"discarded_weight" (Qiskit Aer and ITensor convention: discard the smallest singular values until their cumulative squared weight reaches the threshold) or "relative_max" (discard singular values below threshold * sigma_max). The first compares squared weights, so the same threshold truncates much harder. Only QCSim and GPU support "relative_max"; Aer raises ValueError.
precision	str or None	None	"single" or "double" for Qiskit Aer and the GPU simulators; None keeps each backend’s default. QCSim always uses double precision.
seed	int or None	None	Seeds all backend and Maestro sampling random streams. Parallel jobs derive deterministic, distinct child streams.
gpu_device	int or None	None	CUDA device for single-GPU execution (GPU access only)
distributed_options	dict[str, str]	{}	Settings for DistributedGpu and DistributedMpiGpu, such as distributed_devices, distributed_global_qubits, mpi_communicator and mpi_p2p_bits (GPU access only). See Scaling: multi-GPU and MPI.
gate_fusion	bool or None	None	Fuse compatible gates. None uses each backend’s default: on, except CPU statevectors below 11 qubits and CPU density matrices below 5. Truncated MPS/MPO results can change.
disable_optimized_swapping	bool	False	Turn off swap-cost and initial qubit-map optimization
lookahead_depth	int	-1	Swap optimization lookahead depth; -1 uses the default
mps_routing_strategy	str or None	None	CPU MPS/MPO routing: "legacy" (default) or opt-in "combined". An explicit lookahead overrides it.
mps_routing_virtual_bonds	bool or None	None	Opt into bounded virtual-bond routing on QCSim and GPU MPS and MPO; off by default
mps_routing_truncation_weight	float or None	None	Non-negative overflow penalty relative to capped runtime cost. Default 1; 0 charges runtime alone.
mps_sampling	str	"probabilities"	MPS shot sampling: "probabilities" samples without collapsing the state, "apply_measure" measures and restores it per shot
mps_svd_solver, mpo_svd_solver, tensor_network_svd_solver	str or None	None	GPU SVD solver: "gesvd", "gesvdj", "gesvdp" or "gesvdr"; see GPU SVD algorithm (GPU access only)
mpo_kraus_completeness_check	str or None	None	MPO handling of incomplete Kraus sets: "ignore", "warn" or "strict"
mpo_restore_trace_after_truncation, mpo_hermitize_after_truncation	bool	False	Renormalize the CPU MPO after each truncation
pp_coefficient_threshold	float or None	None	Pauli propagation: drop strings whose coefficient magnitude is at most this
pp_max_pauli_weight	int or None	None	Pauli propagation: drop strings acting on more qubits than this
pp_gates_between_trims, pp_gates_between_deduplications	int or None	None	Pauli propagation: how often, in primitive operations, to apply the two thresholds; deduplication also merges repeated strings. Unset, PauliPropagator deduplicates every 10 operations.
path_integral_threshold	float or None	None	PathIntegral trim threshold
enable_causal_cone_reduction	bool	True	Drop gates and idle qubits outside the backward lightcone of the requested observables
enable_observable_clustering	bool	True	Simulate groups of observables with disjoint lightcones separately, each on its own register
max_cluster_qubits	int or None	None	Also split overlapping lightcones into groups of at most this many qubits; see Bounding group size
min_cluster_qubits	int or None	None	Batch disjoint small lightcones together up to this width, within the maximum
auto_reduce	bool	True	Detect invariant check subspaces and simulate the reduced register on the configured backend
observable_error_tolerance	float or None	None	Opt-in absolute error budget for bounded backward evaluation of exact noisy channels
enable_sampling_reduction	bool	False	Sample disjoint measurement lightcones independently and exactly; changes seeded random streams
allow_reset_marginalization	bool	False	Allow ensemble-equivalent reset marginalization; individual trajectories can change
trajectory_policy	str or None	None	QCSim statevector, density-matrix and path-integral dynamic circuits: "shot_v1" (default) gives streams independent of worker count; "block_v1" keeps earlier seeded counts. Terminal sampling is unaffected.
trajectory_max_memory_mb	int or None	None	Soft budget in MiB for concurrent QCSim dense trajectories; None uses 1024. At least one worker always runs.
max_simulators	int or None	None	Maximum concurrent simulators, from 1 to 1024. None keeps the default; memory budgets may lower it.

Reference

class SimulatorConfig(*args, **kwargs)

Configuration for the quantum simulator backend. Create once and reuse across execute/estimate/statevector calls. Every field is a keyword argument of the constructor.

property allow_reset_marginalization

Allow ensemble-equivalent reset marginalization; individual trajectories can change.

property auto_reduce

Detect check-generated invariant subspaces before estimation and simulate the reduced register using the configured backend; unsupported circuits retain full execution.

property disable_optimized_swapping

Turn off swap-cost optimisation and the initial qubit-map optimisation.

property distributed_options

first global qubits, automatic Ex execution, visible GPUs. MPI calls must match across ranks; mpi_communicator is mpi4py Comm.py2f().

Type:

Distribution settings passed to Configure before allocation. Keys start with distributed_ or mpi_. Defaults

property enable_causal_cone_reduction

Reduce observable causal cones before allocation; distributed GPU backends retain full execution.

property enable_observable_clustering

With causal-cone reduction, partition multi-observable estimates into groups with disjoint lightcones and simulate each on its own compact register. GPU PauliPropagator keeps all observables in one run, since each extra run costs more than it saves.

property enable_sampling_reduction

Opt into exact independent sampling of disjoint measurement cones; changes seeded random streams.

property gate_fusion

on, except for CPU statevectors below 11 qubits and CPU density matrices below 5, where fusion costs more than it saves. True or False force it. Truncated MPS/MPO results can change.

Type:

Fuse compatible gates on supported backends. None (the default) uses each backend’s default

property gpu_device

CUDA-visible device ordinal, or None to use the default.

property lookahead_depth

Lookahead depth for swap optimisation; -1 uses Maestro’s default.

property max_bond_dimension

Largest bond dimension kept when truncating MPS, MPO and GPU tensor-network states. None uses the backend default (128 for GPU MPS and MPO).

property max_cluster_qubits

With observable clustering, split overlapping lightcones into groups of at most this many qubits; a larger single-observable lightcone gets its own group. None uses 20 for statevectors, 10 for density matrices, or connected components for other methods. GPU PauliPropagator ignores it and keeps all observables in one run. With PauliPropagator and pp_gates_between_trims above 1, trims fall on different gates per group, so values can vary with the budget within the truncation error.

property max_simulators

Maximum concurrent simulators, from 1 to 1024. None keeps the network default; CPU and trajectory memory budgets may reduce concurrency.

property min_cluster_qubits

Optionally batch disjoint small cones up to this width, within the maximum budget.

property mpo_hermitize_after_truncation

Make the CPU MPO Hermitian again after each truncation.

property mpo_kraus_completeness_check

‘ignore’, ‘warn’ or ‘strict’ (raise). None uses the default.

Type:

How the MPO simulator treats Kraus operators that do not sum to the identity

property mpo_restore_trace_after_truncation

Rescale the CPU MPO to unit trace after each truncation.

property mpo_svd_solver

GPU SVD solver for MPO truncation; the choices of mps_svd_solver.

property mps_routing_strategy

‘legacy’ (default) or opt-in ‘combined’. Explicit lookahead overrides this selection.

Type:

CPU MPS/MPO automatic routing

property mps_routing_truncation_weight

Nonnegative overflow penalty relative to capped runtime cost. Default 1; zero charges runtime alone.

property mps_routing_virtual_bonds

Opt into bounded virtual-bond routing on QCSim/GPU MPS and MPO; defaults to disabled.

property mps_sampling

How QCSim and Aer MPS simulations sample shots; the GPU MPS simulator ignores it. ‘probabilities’ (the default) samples without collapsing the state; ‘apply_measure’ measures, collapses and restores it for every shot. Both draw from the same distribution, but consume the random stream differently, so one seed gives different counts.

property mps_svd_solver

‘gesvd’, ‘gesvdj’ (Jacobi), ‘gesvdp’ (polar) or ‘gesvdr’ (randomised). None keeps the GPU library’s default.

Type:

GPU SVD solver for MPS truncation

property observable_error_tolerance

Opt-in absolute expectation error budget for bounded backward evaluation of exact noisy channels.

property path_integral_threshold

Trim threshold for PathIntegral simulation; None disables trimming.

property pp_coefficient_threshold

truncation passes drop strings whose |coefficient| is at most this value.

Type:

Pauli propagation

property pp_gates_between_deduplications

every this many operations, merge repeated strings and then apply both thresholds; takes precedence over a trim due on the same operation. Must be positive. Unset, PauliPropagator simulations use 10.

Type:

Pauli propagation

property pp_gates_between_trims

apply both thresholds every this many operations, counting each primitive operation a gate decomposes into. Must be positive.

Type:

Pauli propagation

property pp_max_pauli_weight

truncation passes drop strings acting on more qubits than this; a value at or above the qubit count keeps them all.

Type:

Pauli propagation

property precision

‘single’ or ‘double’ floating point for Qiskit Aer and the GPU simulators. None keeps each backend’s default. Other backends ignore it; QCSim always computes in double precision.

property seed

measurement, readout and reset. The noisy functions also seed their injected noise from its low 32 bits when their noise_seed is unset. None seeds from system entropy.

Type:

Seed for simulation randomness

property simulation_type

Simulation method, a SimulationType.

property simulator_type

Simulator backend, a SimulatorType.

property singular_value_threshold

SVD truncation threshold for MPS, MPO and GPU tensor-network states, read according to truncation_mode. Under ‘relative_max’ it is a ratio of singular values; under ‘discarded_weight’ it bounds the discarded normalised squared weight, so the same number truncates much harder (1e-8 drops singular values up to about 1e-4 of the spectrum’s norm). None uses the backend default.

property tensor_network_svd_solver

GPU SVD solver for tensor-network truncation; the choices of mps_svd_solver.

property trajectory_max_memory_mb

Positive MiB estimate limiting concurrent QCSim dense trajectories. None uses 1024 MiB. This is a soft concurrency budget, not a process memory limit; at least one worker is allowed.

property trajectory_policy

‘block_v1’ preserves existing seeded counts; ‘shot_v1’ distributes individual shots with streams independent of worker count. The policies give different seeded sequences. None uses ‘shot_v1’. Terminal sampling is unaffected.

Type:

QCSim statevector, density-matrix and path-integral dynamic circuits

property truncation_mode

‘relative_max’ drops singular values below singular_value_threshold times the largest; ‘discarded_weight’ (the default on every backend) drops the smallest until their cumulative normalised squared weight reaches the threshold. Only QCSim and the GPU backend support ‘relative_max’; Aer raises if it is requested.

class SimulatorType(*values)

CompositeQCSim = 3

CompositeQiskitAer = 2

DistributedGpu = 6

DistributedMpiGpu = 7

Gpu = 4

QCSim = 1

QiskitAer = 0

QuestSim = 5

class SimulationType(*values)

DensityMatrix = 7

ExtendedStabilizer = 5

MatrixProductOperator = 8

MatrixProductState = 1

PathIntegral = 6

PauliPropagator = 4

Stabilizer = 2

Statevector = 0

TensorNetwork = 3