Metadata-Version: 2.5
Name: mqt-yaqs
Version: 0.7.0
Summary: Scalable simulation and characterization for open systems, noisy circuits, and realistic hardware
Project-URL: Homepage, https://github.com/munich-quantum-toolkit/yaqs
Project-URL: Documentation, https://mqt.readthedocs.io/projects/yaqs
Project-URL: Issues, https://github.com/munich-quantum-toolkit/yaqs/issues
Project-URL: Discussions, https://github.com/munich-quantum-toolkit/yaqs/discussions
Author-email: Aaron Sander <aaron.sander@tum.de>
Maintainer-email: Lukas Burgholzer <burgholzer@me.com>
License-Expression: MIT
License-File: LICENSE
Keywords: MQT,quantum-computing,quantum-simulation,tensor-networks
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Electronic Design Automation (EDA)
Classifier: Topic :: Scientific/Engineering :: Quantum Computing
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: cma>=4
Requires-Dist: numba>=0.61
Requires-Dist: numba>=0.63; python_version >= '3.14'
Requires-Dist: numpy>=1.24
Requires-Dist: numpy>=1.26; python_version >= '3.12'
Requires-Dist: numpy>=2.1; python_version >= '3.13'
Requires-Dist: numpy>=2.3.2; python_version >= '3.14'
Requires-Dist: opt-einsum>=3.4
Requires-Dist: qiskit<3,>=2.1
Requires-Dist: scipy>=1.14.1
Requires-Dist: scipy>=1.16.1; python_version >= '3.14'
Requires-Dist: threadpoolctl>=3.1
Requires-Dist: tqdm>=4.67.1
Provides-Extra: qasm3
Requires-Dist: qiskit-qasm3-import>=0.5; extra == 'qasm3'
Provides-Extra: torch
Requires-Dist: torch!=2.14,!=2.14.1; (sys_platform == 'linux' and platform_machine == 'aarch64') and extra == 'torch'
Requires-Dist: torch>=2.2; extra == 'torch'
Requires-Dist: torch>=2.6; (python_version >= '3.13') and extra == 'torch'
Requires-Dist: torch>=2.9; (python_version >= '3.14') and extra == 'torch'
Description-Content-Type: text/markdown

[![PyPI](https://img.shields.io/pypi/v/mqt.yaqs?logo=pypi&style=flat-square)](https://pypi.org/project/mqt.yaqs/)
![OS](https://img.shields.io/badge/os-linux%20%7C%20macos%20%7C%20windows-blue?style=flat-square)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
[![CI](https://img.shields.io/github/actions/workflow/status/munich-quantum-toolkit/yaqs/ci.yml?branch=main&style=flat-square&logo=github&label=ci)](https://github.com/munich-quantum-toolkit/yaqs/actions/workflows/ci.yml)
[![CD](https://img.shields.io/github/actions/workflow/status/munich-quantum-toolkit/yaqs/cd.yml?style=flat-square&logo=github&label=cd)](https://github.com/munich-quantum-toolkit/yaqs/actions/workflows/cd.yml)
[![Documentation](https://img.shields.io/readthedocs/mqt-yaqs?logo=readthedocs&style=flat-square)](https://mqt.readthedocs.io/projects/yaqs)
[![codecov](https://img.shields.io/codecov/c/github/munich-quantum-toolkit/yaqs?style=flat-square&logo=codecov)](https://codecov.io/gh/munich-quantum-toolkit/yaqs)

<p align="center">
  <a href="https://mqt.readthedocs.io">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/munich-quantum-toolkit/.github/refs/heads/main/docs/_static/logo-mqt-dark.svg" width="60%">
      <img src="https://raw.githubusercontent.com/munich-quantum-toolkit/.github/refs/heads/main/docs/_static/logo-mqt-light.svg" width="60%" alt="MQT Logo">
    </picture>
  </a>
</p>

# MQT YAQS — Simulation and characterization of quantum systems and their environments

MQT YAQS (pronounced "yaks") is a Python library for simulating quantum systems
and studying their interaction with the environment. It supports analog
evolution, noisy quantum circuits, circuit equivalence checking, and
characterization of environmental memory and noise models. It is part of the
[_Munich Quantum Toolkit (MQT)_](https://mqt.readthedocs.io).

YAQS primarily uses tensor networks and quantum trajectories, with statevector
and density matrix backends available for smaller simulations. Tensor network
simulation cost depends strongly on entanglement and accuracy settings, which
can make systems far larger than those accessible to statevector or density
matrix methods practical to simulate. We encourage you to explore larger system
sizes with our package, as we have put thought and effort into making these
methods scalable.

YAQS selects simulation methods from your inputs and provides presets that
balance speed and numerical accuracy. You can get started without tuning every
numerical setting, while still having control over individual settings when
needed.

<p align="center">
  <a href="https://mqt.readthedocs.io/projects/yaqs">
  <img width=30% src="https://img.shields.io/badge/documentation-blue?style=for-the-badge&logo=read%20the%20docs" alt="Documentation" />
  </a>
</p>

## Key Features

Analog, digital, and analog–digital simulations support both noiseless and noisy
dynamics.

| Capability                                                                                                              | What users can do                                                                                                       |
| ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| [Analog simulation](https://mqt.readthedocs.io/projects/yaqs/en/latest/examples/analog_simulation.html)                 | Simulate large quantum systems using tensor networks and Monte Carlo methods.                                           |
| [Digital simulation](https://mqt.readthedocs.io/projects/yaqs/en/latest/examples/circuit_observables.html)              | Simulate quantum circuits using tensor networks and sample measurement outcomes.                                        |
| [Analog–digital simulation](https://mqt.readthedocs.io/projects/yaqs/en/latest/examples/digital_analog_simulation.html) | Combine analog evolution and quantum circuits in one simulation.                                                        |
| [Equivalence checking](https://mqt.readthedocs.io/projects/yaqs/en/latest/examples/equivalence_checking.html)           | Check whether two quantum circuits behave the same, measure differences, and study the effects of noise on compilation. |
| [Environmental memory](https://mqt.readthedocs.io/projects/yaqs/en/latest/examples/characterization.html)               | Study a system's environment and understand memory effects from past interactions.                                      |
| [Surrogate models](https://mqt.readthedocs.io/projects/yaqs/en/latest/examples/memory_surrogate.html)                   | Train models to predict dynamics that depend on past interactions (non-Markovian dynamics; requires PyTorch).           |
| [Noise characterization](https://mqt.readthedocs.io/projects/yaqs/en/latest/examples/digital_twin.html)                 | Learn a system's noise model from its observed dynamics.                                                                |
| [Hardware modeling](https://mqt.readthedocs.io/projects/yaqs/en/latest/examples/hamiltonians.html)                      | Use device Hamiltonians together with realistic noise models.                                                           |

If you have any questions, feel free to create a
[discussion](https://github.com/munich-quantum-toolkit/yaqs/discussions) or an
[issue](https://github.com/munich-quantum-toolkit/yaqs/issues) on
[GitHub](https://github.com/munich-quantum-toolkit/yaqs).

## Getting Started

MQT YAQS requires **Python 3.11 or newer** and runs on Linux, macOS, and
Windows. Install it from [PyPI](https://pypi.org/project/mqt.yaqs/) in a virtual
environment using `uv`:

```console
uv pip install mqt.yaqs
```

Or use `pip`:

```console
python -m pip install mqt.yaqs
```

See the
[installation guide](https://mqt.readthedocs.io/projects/yaqs/en/latest/installation.html)
for environment setup and development installation.

Optional extras support
[OpenQASM 3 input](https://mqt.readthedocs.io/projects/yaqs/en/latest/examples/circuit_observables.html)
(`qasm3`) and
[surrogate training and prediction](https://mqt.readthedocs.io/projects/yaqs/en/latest/examples/memory_surrogate.html)
(`torch`). The linked guides include installation steps.

### Noisy analog evolution

Evolve a 50-site Ising chain with local damping and print the final mean ⟨Z₀⟩.

```python
from mqt.yaqs import AnalogSimParams, Hamiltonian, NoiseModel, Observable, Simulator, State

if __name__ == "__main__":
    length = 50
    state = State(length, initial="zeros")
    hamiltonian = Hamiltonian.ising(length, J=1.0, g=0.5)
    noise = NoiseModel([{"name": "lowering", "sites": [site], "strength": 0.05} for site in range(length)])
    params = AnalogSimParams(
        observables=[Observable("z", sites=0)],
        elapsed_time=1.0,
        dt=0.1,
    )
    simulator = Simulator()
    result = simulator.run(state, hamiltonian, params, noise)
    print(f"Final mean <Z_0>: {result.expectation_values[0][-1]:.3f}")
```

For more information, read the
[analog simulation guide](https://mqt.readthedocs.io/projects/yaqs/en/latest/examples/analog_simulation.html).

### Noisy circuit simulation

Prepare a 50-qubit GHZ circuit with local damping and print sampled bitstring
counts.

```python
from qiskit.circuit import QuantumCircuit

from mqt.yaqs import DigitalSimParams, NoiseModel, Simulator, State

if __name__ == "__main__":
    length = 50
    state = State(length, initial="zeros")
    circuit = QuantumCircuit(length)
    circuit.h(0)
    for site in range(1, length):
        circuit.cx(site - 1, site)
    circuit.measure_all()

    noise = NoiseModel([{"name": "lowering", "sites": [site], "strength": 0.05} for site in range(length)])
    params = DigitalSimParams(shots=1024)
    simulator = Simulator()
    result = simulator.run(state, circuit, params, noise)
    print({format(outcome, f"0{length}b"): count for outcome, count in result.counts.items()})
```

For more information, read the
[shot-readout guide](https://mqt.readthedocs.io/projects/yaqs/en/latest/examples/circuit_shots.html).

### Environmental memory characterization

Probe environmental memory in a 50-site chain and print the memory diagnostics.

```python
from mqt.yaqs import AnalogSimParams, Hamiltonian, MemoryCharacterizer

if __name__ == "__main__":
    hamiltonian = Hamiltonian.ising(length=50, J=1.0, g=1.0)
    params = AnalogSimParams(dt=0.1)
    characterizer = MemoryCharacterizer()
    result = characterizer.characterize(
        hamiltonian,
        params,
        num_interventions=6,
        preset="quick",
    )
    print(result.summary())
```

For more information, read the
[memory characterization guide](https://mqt.readthedocs.io/projects/yaqs/en/latest/examples/characterization.html).

Trajectory count, time-step size, and MPS truncation affect numerical accuracy;
see the
[simulation parameter guide](https://mqt.readthedocs.io/projects/yaqs/en/latest/examples/simulation_parameters.html).

The examples use default parallel execution. See the
[execution guide](https://mqt.readthedocs.io/projects/yaqs/en/latest/examples/simulator_initialization.html)
for worker controls.

**Documentation:**
[Quickstart](https://mqt.readthedocs.io/projects/yaqs/en/latest/examples/quickstart.html)
·
[API reference](https://mqt.readthedocs.io/projects/yaqs/en/latest/api/mqt/yaqs/index.html)
·
[Full documentation](https://mqt.readthedocs.io/projects/yaqs)

## Contributors and Supporters

The _[Munich Quantum Toolkit (MQT)](https://mqt.readthedocs.io)_ is developed by
the [Chair for Design Automation](https://www.cda.cit.tum.de/) at the
[Technical University of Munich](https://www.tum.de/) and supported by
[MQSC](https://mq.sc). Among others, it is part of the
[Munich Quantum Software Stack (MQSS)](https://www.munich-quantum-valley.de/research/research-areas/mqss)
ecosystem, which is being developed as part of the
[Munich Quantum Valley (MQV)](https://www.munich-quantum-valley.de) initiative.

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/munich-quantum-toolkit/.github/refs/heads/main/docs/_static/mqt-logo-banner-dark.svg" width="90%">
    <img src="https://raw.githubusercontent.com/munich-quantum-toolkit/.github/refs/heads/main/docs/_static/mqt-logo-banner-light.svg" width="90%" alt="MQT Partner Logos">
  </picture>
</p>

Thank you to all the contributors who have helped make MQT YAQS a reality!

<p align="center">
  <a href="https://github.com/munich-quantum-toolkit/yaqs/graphs/contributors">
    <img src="https://contrib.rocks/image?repo=munich-quantum-toolkit/yaqs" />
  </a>
</p>

The MQT will remain free, open-source, and permissively licensed—now and in the
future. We are firmly committed to keeping it open and actively maintained for
the quantum computing community.

To support this endeavor, please consider:

- Starring and sharing our repositories:
  <https://github.com/munich-quantum-toolkit>
- Contributing code, documentation, tests, or examples via issues and pull
  requests
- Citing the MQT in your publications (see [Cite This](#cite-this))
- Citing our research in your publications (see
  [References](https://mqt.readthedocs.io/projects/yaqs/en/latest/references.html))
- Using the MQT in research and teaching, and sharing feedback and use cases
- Sponsoring us on GitHub: <https://github.com/sponsors/munich-quantum-toolkit>

<p align="center">
  <a href="https://github.com/sponsors/munich-quantum-toolkit">
  <img width=20% src="https://img.shields.io/badge/Sponsor-white?style=for-the-badge&logo=githubsponsors&labelColor=black&color=blue" alt="Sponsor the MQT" />
  </a>
</p>

## Cite This

If you use YAQS in academic work, please cite both the
[YAQS software](#yaqs-software) and the [MQT Handbook](#mqt-handbook). Also cite
the papers for the methods you use.

### YAQS software

We expect to replace this software citation with a dedicated YAQS publication.
Please use the citation below for now.

```bibtex
@misc{YAQS,
  author       = {Aaron Sander},
  title        = {{YAQS}: Yet Another Quantum Simulator},
  year         = {2025},
  howpublished = {\url{https://github.com/munich-quantum-toolkit/yaqs}}
}
```

### MQT Handbook

[[8]](https://doi.org/10.1109/QSW62656.2024.00013) R. Wille et al. The MQT
Handbook: A Summary of Design Automation Tools and Software for Quantum
Computing. _IEEE International Conference on Quantum Software (QSW)_ (2024).

### Research publications

When citing the underlying methods and research, please reference the most
relevant publications from the list below:

[[1]](https://www.nature.com/articles/s41467-025-66846-x) A. Sander, M.
Fröhlich, M. Eigel, J. Eisert, P. Gelß, M. Hintermüller, R. M. Milbradt, R.
Wille, C. B. Mendl. Large-scale stochastic simulation of open quantum systems.
_Nature Communications_ _16_, 11074 (2025).

[[2]](https://journals.aps.org/prresearch/abstract/10.1103/3q71-y8cf) A. Sander,
L. Burgholzer, and R. Wille. Equivalence checking of quantum circuits via
intermediary matrix product operator. _Phys. Rev. Research_ _7_, 023261 (2025).

[[3]](https://arxiv.org/abs/2508.10096) A. Sander, M. Fröhlich, M. Ali, M.
Eigel, J. Eisert, M. Hintermüller, C. B. Mendl, R. M. Milbradt, R. Wille.
Quantum circuit simulation with a local time-dependent variational principle.
_arXiv:2508.10096 (2025)._

[[4]](https://arxiv.org/abs/2606.13779) A. Sander, S. Cichy, M. Eigel, J.
Eisert, M. Fröhlich, T. Peham, R. Wille. Computational regimes in
matrix-product-state-based quantum trajectory simulations.
_arXiv:2606.13779 (2026)._

[[5]](https://arxiv.org/abs/2607.01323) M. Fröhlich, A. Sander, M. Eigel, R.
Wille, M. Hintermüller. Noisy quantum circuit simulation with the tensor jump
method. _arXiv:2607.01323 (2026)._

[[6]](https://arxiv.org/abs/2608.24668) A. R. Ramos Ramos, M. Fröhlich, A.
Sander, R. Wille, M. Eigel, P. Gelß, S. Pokutta. Scalable Lindblad Noise
Learning via Stochastic Tensor-Network Simulation. _arXiv:2608.24668 (2026)._

[[7]](https://arxiv.org/abs/2608.16994) M. Fröhlich, R. M. Milbradt, M. Eigel,
A. Sander, R. Wille, C. B. Mendl. Basis-update and Galerkin time integration in
canonical matrix-product-state form. _arXiv:2608.16994 (2026)._

---

## Acknowledgements

The Munich Quantum Toolkit has been supported by the European Research Council
(ERC) under the European Union's Horizon 2020 research and innovation program
(grant agreement No. 101001318), the Bavarian State Ministry for Science and
Arts through the Distinguished Professorship Program, as well as the Munich
Quantum Valley, which is supported by the Bavarian state government with funds
from the Hightech Agenda Bayern Plus.

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/munich-quantum-toolkit/.github/refs/heads/main/docs/_static/mqt-funding-footer-dark.svg" width="90%">
    <img src="https://raw.githubusercontent.com/munich-quantum-toolkit/.github/refs/heads/main/docs/_static/mqt-funding-footer-light.svg" width="90%" alt="MQT Funding Footer">
  </picture>
</p>
