# Quantum++: header-only C++ quantum simulation with Eigen underneath

> Quantum++ is a C++17 quantum computing library made entirely of template headers, depending only on Eigen for linear algebra and OpenMP where available. It simulates arbitrary quantum processes rather than only qubit systems, and the same repository ships a Python binding built with pybind11.

**softwareQinc/qpp** — Modern C++ quantum computing library

- Repository: https://github.com/softwareQinc/qpp
- Website: https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0208073
- Stars: 677 · Forks: 145
- Language: C++
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/softwareqinc-qpp

## A header-only library with one real dependency

Quantum++ is described as a modern C++ general purpose quantum computing library, composed solely of template header files. It is written in standard C++17 and has very low external dependencies, using only the Eigen linear algebra header-only template library and, if available, the OpenMP multiprocessing library.

That dependency list is short enough to be the main argument for the library. There is no quantum-specific runtime, no plugin system, no build-time code generation step and no external state manager. You add the include directory, you add Eigen, and you compile. For a library that ends up inside a larger simulation or research binary, that matters, because every additional dependency is a portability problem on the platforms Eigen itself has to support.

The scope claim is also broader than the name suggests. The README says Quantum++ is not restricted to qubit systems or specific quantum information processing tasks, and is capable of simulating arbitrary quantum processes. That is a real difference from libraries built around a fixed gate set, and it is what makes the library general purpose rather than a teaching aid.

The stated design factors are ease of use, high portability and high performance, and there is a hard limit stated as well: the library's simulation capabilities are only restricted by the amount of available physical memory. That is the honest boundary of a state-vector simulator, and it is worth internalising before choosing it for a problem size.

The audience is a C++ developer with a solid grasp of modern C++ including templates, some knowledge of quantum computing and linear algebra, and working experience with Eigen, since the contribution guide asks for exactly that. The homepage is a PLOS ONE article on the library, and the copyright runs from 2017 to 2026 softwareQ Inc.

## The example set is where the library actually documents itself

The repository's examples directory is unusually broad, and reading it is the fastest way to understand the scope of the library.

The protocol and algorithm examples include bb84, dense coding, entanglement, grover, hhl, gram_schmidt, bell_inequalities, channels, noise and exceptions. There are examples for gates and states, for measurement, for input and output, for matrix layout, for the functor, for entropies, and for graph states. There is a minimal example, which is the one to look at first if you want to see the smallest possible program.

There are also directories for circuits and for qasm, and a separate qasmtools/ directory at the repository root, which suggests QASM handling is a first-class part of the library rather than a side utility.

The README points at the examples directory for a comprehensive look at the library in action, and also points at a community-contributed examples repository maintained by another developer, which is a good sign for a project with a user base beyond its own maintainers.

The unit_tests/ directory at the root and a benchmarks/ directory are both present, and the CI badge points at a cmake workflow rather than a language-specific one, so the build is CMake-based. The top level also carries .clang-format and .clang-tidy, so the C++ style is enforced by tooling, and a prettyprint.sh script for formatting.

Two more files at the root are worth knowing about. CHANGES.md is the changelog, and DISCREPANCIES.md is a document about differences from other implementations or reference behaviour. For a numerical library, a discrepancies document is a sign of care, and it is the first place to look when your results do not match someone else's.

## The Python binding is a wrapper, and it builds the C++ library

The repository ships pyqpp, a Python 3 wrapper for Quantum++, and the distinction matters for anyone choosing an interface.

The wrapper requires the same dependencies as the library itself, and the install command pulls the whole repository from GitHub rather than a tagged release.

```shell
pip install git+https://github.com/softwareQinc/qpp
```

The pyproject.toml explains what that involves. The distribution is named pyqpp at version 7.0.3, requires Python 3.9 or newer, and depends on numpy. The build system requires numpy, pybind11, scikit-build-core and wheel, with scikit-build-core as the build backend. The scikit-build section defines a CMake variable for the internal build flag, installs a component named python, and maps the wheel packages to a path inside the pyqpp directory. The macOS wheel is configured to expand universal tags, which is what lets a single wheel cover both architectures.

So the Python route is not a lightweight reimplementation. It is a pybind11 binding over the C++ library, built through CMake by scikit-build-core. That means the Python install compiles the C++, which means it needs a compiler toolchain, which is the opposite of what a pip install normally implies.

The practical rule that follows is simple. If your project is C++, use Quantum++ directly and take the header-only path with Eigen and no build system at all. If your project is Python, decide whether you want the compile step, because the wrapper is a real dependency on the native library rather than a self-contained package.

## Building the documentation needs Doxygen, Graphviz and a LaTeX toolchain

The documentation instructions are the most detailed part of the README, and they tell you what the project expects of a contributor.

The installation guide is in INSTALL.md and there is a comprehensive Wiki for further documentation and detailed examples. To generate the full official API documentation in both LaTeX and HTML formats you run doxygen on the Doxyfile, and the tool dot from the Graphviz package must be installed.

```shell
sudo apt-get install graphviz
```

On macOS the equivalent is brew install graphviz. The Doxyfile is in the repository root, and running doxygen produces a doc directory containing both the HTML and the LaTeX documentation. The HTML output is browsable by opening doc/html/index.html.

The PDF route is a second step on top of that. You run latexmk with the pdf target on refman.tex, either from the doc/latex directory or by compiling the file doc/latex/refman.tex directly with your LaTeX compiler, which produces doc/latex/refman.pdf.

```shell
latexmk -pdf refman.tex
```

Three separate toolchains are therefore involved in producing the full documentation: Doxygen for extraction, Graphviz for the graph rendering, and a LaTeX distribution for the manual. None of them are needed to use the library, and the library itself needs no build step at all beyond compiling your own program, which is the direct consequence of being header-only.

One small detail: the README's LaTeX instruction is written with a file named refman.tex, and the top level listing contains a Doxyfile but no refman.tex, so that file is produced by the Doxygen run rather than checked in.

## Where Quantum++ is the wrong tool

The first wrong-tool case is a Python-first team that wants a pip-installable quantum library. The pyqpp binding works, but it compiles the C++ through CMake on the way in, and the dependency floor is a C++17 toolchain plus Eigen plus a Python with pybind11 and scikit-build-core available. If your requirement is an import and go, that is a different shape of library.

The second case is a problem size that does not fit in memory. The README states the limit plainly: simulation capabilities are only restricted by the amount of available physical memory. A state-vector simulator holds the full state vector, so the number of qubits you can simulate scales with memory, and the useful limit is reached well before the theoretical one. The library does not offer a tensor network or a stabilizer representation in the visible documentation, and for a large or structured problem a different simulator is the right instrument.

The third case is a project that wants a stable, versioned API with a compatibility promise. The releases here are version 7.0.1, 7.0.2 and 7.0.3 within four days of each other in March 2026, which is a fast-moving line, and the last push was on 2026-07-20. The major version number has moved, which is what a seven-year-old library with active churn looks like, and the version in the README is 7.0.3 from 25 March 2026. Nothing here is deprecated or archived, but the pin in your build system should be deliberate.

The fourth case is a team without Eigen experience. The contribution guide asks for working experience with Eigen specifically, and the reason is that Eigen's expression templates interact with the way the library's state and gate operations are written. Using the library does not require that expertise, but reading its internals and extending it does.

On licensing, Quantum++ is distributed under the MIT License with a LICENSE.txt file at the root, and the copyright is held by softwareQ Inc. from 2017 to 2026. There is also a CODE_OF_CONDUCT.md and a CONTRIBUTING.md, and a pyrightconfig.json at the root for type checking the Python side. The project is published in a PLOS ONE journal article, which is the reference to read if you want the design rationale rather than the usage notes.

## Conclusion

Quantum++ suits a C++ developer who needs to simulate quantum processes inside an existing native codebase, since the library is header-only, depends on Eigen rather than on a large toolchain, and lets you mix quantum routines with ordinary C++ without crossing a language boundary. It does not suit a Python-first team, since the pyqpp binding is a wrapper with its own build rather than the primary interface, and it does not suit a project whose simulation sizes exceed available memory, because the state vector is held explicitly. Before adopting, read INSTALL.md for the build options, expect to provide Eigen yourself, and check the DISCREPANCIES.md file when your results disagree with a reference implementation.

## FAQ

### What is Quantum++?

Quantum++ is a modern C++ general purpose quantum computing library composed solely of template header files, written in standard C++17, and able to simulate arbitrary quantum processes rather than only qubit systems. Its only external dependencies are the Eigen linear algebra library and, where available, OpenMP.

### What are the dependencies for Quantum++?

Only the header-only Eigen linear algebra library and, if available, OpenMP for multiprocessing. The library itself needs no build step, since it is composed entirely of template headers, and the installation details are in INSTALL.md.

### How do I install the pyqpp Python wrapper?

With pip install git+https://github.com/softwareQinc/qpp, which requires the same dependencies as the C++ library. The wrapper is built with pybind11 and scikit-build-core, so installing it compiles the C++ and needs a toolchain.

### How do I generate the Quantum++ API documentation?

Run doxygen on the Doxyfile in the repository root, with the dot tool from the Graphviz package installed. That produces a doc directory with both HTML and LaTeX output, browsable at doc/html/index.html, and a PDF can be produced with latexmk -pdf refman.tex from the doc/latex directory.

### What license is Quantum++ released under?

Quantum++ is distributed under the MIT License, with the LICENSE.txt file at the root of the repository. The copyright is held by softwareQ Inc. from 2017 to 2026.

## Sources

- [License: MIT](https://github.com/softwareQinc/qpp/blob/main/LICENSE)
- [Project website](https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0208073)
- [README](https://github.com/softwareQinc/qpp/blob/main/README.md)
- [Releases](https://github.com/softwareQinc/qpp/releases)
- [softwareQinc/qpp on GitHub](https://github.com/softwareQinc/qpp)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/softwareqinc-qpp