Maestro 0.3.1
Unified interface for quantum circuit simulation
Loading...
Searching...
No Matches
Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

0.3.1 - 2026-09-10

Added

  • Native Delay & Idle Operation: Added first-class Delay instruction across Circuit IR, Factory, Python bindings (qc.delay), and OpenQASM 2/3 parsers with duration validation in seconds.
  • Idle Channel Decoherence: Introduced idle channel simulation via set_idle_noise(qubit, t1, t2, excited_population, detuning_hz) to model thermal relaxation, phase decay, and coherent detuning rotation accumulated over idling intervals.
  • Continuous OU Noise Integration: Integrated continuous-time Ornstein-Uhlenbeck (OU) dephasing during delays, analytically propagating correlated frequency fluctuations across arbitrary idle durations.
  • Multi-Band OU & 1/f Spectrum Noise: Added multi-band OU dephasing support (add_correlated_ou_band, set_multi_correlated_ou, set_all_multi_correlated_ou), synthetic 1/f noise generation (set_1_over_f_noise), and stationary equilibrium initialization (stationary_init).
  • Sinter Integration: Added maestro.sinter module with MaestroSinterSampler and MaestroCompiledSampler implementing Sinter's sampling interface for Stim-based quantum error correction (QEC) benchmarking.
  • GPU SVD Algorithm Selection: Added configuration parameters in SimulatorConfig to select specialized GPU SVD solvers (gesvd, gesvdj, gesvdp, gesvdr) for MPS, MPO, and Tensor Network backends.

Changed

  • Python package version bumped to 0.3.1.

0.3.0 - 2026-09-07

Added

  • GPU Density Matrix Simulator: Added full density matrix simulation on GPU (SimulationType.kDensityMatrix with SimulatorType.kGpuSim) for exact mixed-state quantum simulation.
  • GPU Matrix Product Operator (MPO) Simulator: Added GPU-accelerated MPO simulation (SimulationType.kMatrixProductOperator with SimulatorType.kGpuSim), supporting non-unitary noise, truncation thresholding, trimming, and recanonicalization.
  • QCSim Extended Stabilizer Simulator: Added extended stabilizer simulation backend support in QCSim for near-Clifford circuit execution.
  • CPTP Quantum Channels & Exact Noise Models: Introduced QuantumChannel and QuantumChannelOperation classes supporting general Kraus representations, along with predefined channels (bit-flip, phase-flip, depolarizing, amplitude damping, phase damping, and thermal relaxation).
  • Deterministic Simulation Seeding: Exposed seed parameter in SimulatorConfig and across simulator backends for reproducible stochastic simulations.
  • GPU Device Selection: Added interface to select the target GPU device for GPU simulator backends.
  • OpenQASM 3 Support: Added OpenQASM 3 import and export capabilities.
  • Documentation Rework: Restructured Python API documentation into dedicated guides for backends, HPC execution, noise simulation, algorithms, and quickstart reference.

Fixed

  • Bond Dimension Capping & Synchronization: Configured default MPS and MPO bond dimension to 128 in GpuState and GPU plugin to prevent unbounded device memory allocation.
  • Mirror Fidelity Validation: Added validation in mirror_fidelity to raise informative errors if simulation yields zero measurement samples or zero shots instead of failing silently.
  • Pauli Propagation: Fixed GPU Pauli destructive state hooks and truncation configuration propagation.

Changed

  • Python package version bumped to 0.3.0.

0.2.18 - 2026-08-13

Added

  • Bond dimension tracking per time step in incremental_evolve
  • Simulators and networks Configuration classes and refactoring

Fixed

  • Misaligned time step guard handling in network evolution

Changed

  • Python package version bumped to 0.2.18

0.2.17 - 2026-08-11

Added

  • Bond Dimension Callback & Max Bond Dimension Tracking — exposed maximum bond dimension reached during MPS simulation across execute, estimate, and incremental_evolve Python return dictionaries (max_bond_dim_reached)
  • Integrated QCSim bond dimension callback support and GPU MPS simulator bond dimension callback
  • Added simulator Configuration class to standardise parameter delivery across simulator backends

Changed

  • Python package version bumped to 0.2.17

0.2.13 - 2026-05-02

Added

  • Asymmetric readout error — set_readout_error(q, p_meas1_prep0, p_meas0_prep1), set_readout_error_symmetric(q, p), set_all_readout_error(n, p) for per-qubit classical measurement error modelling. Applied as a post-measurement channel in noisy_execute and full_noise_execute
  • Two-qubit depolarizing channel — set_2q_depolarizing(q1, q2, p) for correlated 15-Pauli noise applied after CX/CZ gates on specific qubit pairs
  • Gate-type-specific depolarizing — set_1q_gate_depolarizing(q, p) and set_2q_gate_depolarizing(q, p) for separate noise rates after single-qubit vs two-qubit gates, with bulk setters set_all_1q_gate_depolarizing and set_all_2q_gate_depolarizing
  • qc.noisy_prob(target, nm) — readout-corrected path integral probability using first-order analytic expansion (n+1 PI evaluations instead of Monte Carlo)
  • Readout error, two-qubit depolarizing, gate-type-specific noise, and noisy_prob sections in python.dox (Doxygen) and TUTORIAL.md
  • Complete NoiseModel method reference table in both documentation sources

Changed

  • Python package version bumped to 0.2.13
  • Fixed set_pauli_channel documentation to use correct binding name set_qubit_noise

0.2.12 - 2026-04-28

Added

  • Path Integral simulation backend — new exact-amplitude simulator (kPathIntegral) integrated into the QCSim common interface, supporting amplitudes, measurements, sampling, and Pauli-string expectation values. Exposed through the factory and the SimulatorConfig(simulator_type="path_integral") Python API
  • Path Integral Python bindings — amplitude_from_zero() and amplitude() methods on QuantumCircuit for computing exact transition amplitudes via path integrals
  • IsBranching() method on all quantum gate types, used by the path integral simulator to identify branching operations
  • Path Integral via Network interface — SimpleDisconnectedNetwork now dispatches path integral jobs; multithreading is disabled for path integral simulators in networks when measurements are only at the end
  • Coherent noise model — NoiseModel now supports deterministic rotation-gate noise injection (Rx/Ry/Rz) alongside stochastic Pauli channels. Coherent angle is derived from error probability via ε = 2·arcsin(√p) to match per-gate infidelity
  • Coherent noise setters: set_coherent_depolarizing(), set_coherent_dephasing(), set_coherent_bit_flip(), set_coherent_rotation(), set_all_coherent_depolarizing()
  • T1 amplitude damping noise — set_t1(), set_all_t1(), set_t1_from_time() for per-qubit T1 decay with physical time-constant conversion (γ = 1 − e^(−t_gate/T₁))
  • ZZ crosstalk noise — set_crosstalk() for pairwise qubit coupling injection
  • coherent_execute / coherent_estimate — Python bindings for executing circuits and estimating expectation values with coherent rotation noise
  • full_noise_execute / full_noise_estimate — combined noise pipeline applying coherent + crosstalk + T1 + Pauli noise in a single call
  • Comprehensive test suites: 600+ lines of path integral C++ tests (random circuits, amplitudes, measurements, sampling, Pauli strings), 290+ lines of network simulator tests, 1200+ lines of new Python binding tests covering all noise modes
  • Noise simulation and path integral sections in TUTORIAL.md with usage examples

Changed

  • NoiseModel header expanded to support Pauli, coherent, T1, and crosstalk noise in a unified model — both modes can be configured on the same instance
  • QCSimSimulator routes all gate types through the path integral backend when kPathIntegral simulation type is selected
  • QCSimState extended with path integral simulator state management, amplitude computation, and measurement support
  • Doxygen upgraded to latest version; docs CI workflow updated
  • Python package version bumped to 0.2.12

Fixed

  • Missing public: access specifier on PathIntegralSimulator class methods
  • Include path issues for Linux compilation in network simulator tests
  • Compile warnings in NetworkJob.h and SimpleDisconnectedNetwork.h

0.2.11 - 2026-04-20

Added

  • Python 3.13 and 3.14 wheels published to PyPI for Linux, macOS, and Windows
  • QasmToCirc.failed() and QasmToCirc.get_error_message() Python bindings for inspecting parser state after a failed parse
  • QASM parser: id gates and unrecognised no-op instructions are now silently skipped instead of raising

Changed

  • SimulatorConfig struct — all execution, estimation, and fidelity functions now accept a single config=maestro.SimulatorConfig(...) parameter instead of repeating simulator_type, simulation_type, max_bond_dimension, singular_value_threshold, use_double_precision, disable_optimized_swapping, lookahead_depth, and mps_measure_no_collapse as individual keyword arguments. Create a config once and reuse it across calls.
  • Updated all Python examples to use the new SimulatorConfig API
  • Updated python.dox and TUTORIAL.md documentation with SimulatorConfig usage
  • QasmToCirc.parse_and_translate now raises ValueError carrying the parser error message when QASM input is invalid, instead of returning a bad circuit silently
  • Build toolchain: cibuildwheel upgraded from v2.22.0 to v3.4.1; default Linux manylinux image moved from manylinux2014 to manylinux_2_28 (wheels now require glibc 2.28+, i.e. RHEL 8 / Ubuntu 20.04 / Debian 10 or newer)
  • MPS swap optimization: growthFactorGate heuristic tuned from 0.7 to 0.65 across QCSim, GPU, MPSDummy, and SimpleDisconnectedNetwork — may shift swap-vs-gate planning decisions on large circuits

Fixed

  • simple_execute (QASM variant) was not forwarding mps_measure_no_collapse to the simulator
  • noisy_estimate_montecarlo was not forwarding mps_measure_no_collapse to noisy runs
  • mirror_fidelity returned incorrect values because the circuit optimizer cancelled the mirror's paired gate/adjoint operations before execution. Circuit optimization and MPS swap optimization are now disabled for the mirror run, and non-gate operations (e.g. measurements) are skipped during the adjoint reverse pass
  • SampleCountsMany on the Qiskit Aer MPS backend returned bits in ascending-qubit-index order rather than the caller-requested qubit order, silently misaligning outcomes. Bits are now remapped to match the caller order (consistent with the statevector backend)
  • singular_value_threshold values below ~1e-4 were truncated to 0 when serialized to the MPS backend (via std::to_string's default 6-digit precision), effectively disabling entanglement truncation. Serialization now uses max_digits10 (17 significant digits)

0.2.10 - 2026-04-16

Added

  • Noise simulation API — NoiseModel class for per-qubit Pauli noise channels (depolarizing, dephasing, bit-flip, custom)
  • noisy_estimate — analytical Pauli channel damping with zero simulation overhead for fast ansatz noise screening
  • noisy_estimate_montecarlo — gate-by-gate Monte Carlo noisy estimation for accurate depth-dependent noise simulation
  • noisy_execute — Monte Carlo shot-based noisy circuit execution with batched noise realizations
  • Noise model helpers: set_depolarizing, set_dephasing, set_bit_flip, set_pauli_channel, set_all_depolarizing
  • Comprehensive noise test suite (25 tests covering NoiseModel, analytical damping, Monte Carlo estimation, and execution)
  • Noise simulation section in TUTORIAL.md with usage examples and parameter reference

Changed

  • Default lookahead_depth changed from 20 to -1 (auto-tuning) to prevent hangs on larger MPS circuits

Fixed

  • MPS swap optimization hang on larger circuits caused by hardcoded lookahead_depth=20 bypassing the C++ auto-tuning heuristic

0.2.7 - 2026-03-27

Added

  • Inner product — compute ⟨ψ₁|ψ₂⟩ between two circuits via ProjectOnZero (maestro.inner_product(circ_1, circ_2) and qc.inner_product(other))
  • Python documentation for inner_product in python.dox
  • Comprehensive test suite for inner product (9 tests covering identical, orthogonal, parametric, MPS, and phase-difference cases)

0.2.6 - 2026-03-25

Added

  • ProjectOnZero — efficient ⟨0|ψ⟩ projection for all simulator backends (QCSim MPS, GPU MPS, statevector, composite)
  • ExecuteOnHostProjectOnZero network-level method with qubit remapping support
  • ExecuteOnHostAmplitudes with proper qubit remapping for statevector extraction
  • Mirror fidelity — maestro.mirror_fidelity() and qc.mirror_fidelity() with shot-based and exact statevector modes
  • Statevector access — maestro.get_statevector() and qc.get_statevector() Python bindings
  • Probability access — maestro.get_probabilities() Python binding
  • MPS swap optimization with lookahead heuristics and initial qubit mapping
  • Classically controlled gate support for MPS lookahead swap optimization
  • Improved QCSim MPS sampling for partial qubit measurements
  • ProjectOnZero C++ tests across all simulator backends

Fixed

  • Linux GPU library compilation (missing include)
  • MPS optimization test adjusted from 20 to 12 qubits for stability

0.2.5 - 2026-03-18

Added

  • Windows wheel support — pre-built wheels for Windows AMD64 (Python 3.10, 3.11, 3.12) published to PyPI
  • vcpkg-based dependency management for Windows CI builds
  • Dry-run Windows CI workflow

Fixed

  • Eigen type mismatch between Windows and Linux (Eigen::Index → long long int)
  • OpenMP configuration on Windows
  • Compile warnings in MPS simulator and QCSim

0.2.4 - 2026-03-12

Changed

  • Split Python version builds into separate CI matrix elements for faster Windows builds
  • Code styling and minor CI workflow improvements

0.2.3 - 2026-03-07

Added

  • Exposed setting the initial qubits map from the Python API
  • MPS swap cost optimization with improved heuristics

Fixed

  • Linux wheel repair (auditwheel) patching for libmaestro linkage
  • rpath configuration ($ORIGIN) for reliable library resolution in wheels

0.2.2 - 2026-03-01

Fixed

  • Bundled excluded libmaestro shared library with Python wheel
  • macOS build issues

0.2.1 - 2026-02-25

Fixed

  • PyPI package metadata issue
  • Version bump for initial stable release

Added

  • Python bindings via nanobind with QuantumCircuit model and GPU support
  • PyPI distribution with scikit-build-core and cibuildwheel for Linux & macOS
  • Pauli propagator simulator — CPU and GPU implementations with non-Clifford gate decomposition
  • Extended stabilizer simulator with support for > 64 qubits
  • QuEST simulator integration with factory function and tests
  • GPU stabilizer simulator exposed through the library API
  • Rydberg atom array simulation examples (adiabatic preparation, phase diagrams, spatial correlations)
  • MPS parameters passthrough in the SimpleExecute flow
  • Expectation value estimation via Python (SimpleEstimate)
  • Maestro executable support for new simulators (Pauli propagator, extended stabilizer, QuEST)
  • Double-precision toggle from Python bindings
  • ccache support for faster rebuilds
  • Doxygen documentation GitHub Actions workflow

Changed

  • Refactored GitHub Actions CI workflow for better dependency caching
  • Build system configured for PyPI distribution (rpath, install targets)
  • Improved GPU precision handling with placeholder params

Fixed

  • macOS OpenMP/install build issues
  • Linux GPU compilation errors
  • Circuit distribution crash when no distributor is present in disconnected networks
  • Build warnings suppressed for third-party dependencies

0.1.0 - 2026-01-18

Added

  • Core simulation engine with multi-backend support (QCSim statevector, MPS tensor network, Qiskit Aer, Clifford)
  • Composite simulator for automatic circuit distribution across backends
  • GPU tensor network simulator with statevector and stabilizer support
  • Maestro shared library (libmaestro) with SimpleExecute JSON/QASM API
  • Maestro standalone executable with command-line interface
  • QASM 2.0 parser (string → circuit conversion) with standard gate support
  • Expectation value estimation framework
  • Network-based job scheduling and execution
  • OpenMP parallelization with SIMD (AVX2/FMA) acceleration
  • Boost serialization support
  • Doxygen API documentation with GitHub Pages deployment
  • GitHub Actions CI (Ubuntu build + test)
  • Pre-commit hooks with clang-format code formatting
  • CITATION.cff, CODE_OF_CONDUCT.md, CONTRIBUTING.md, INSTALL.md