From bb52d66d62d4d1cfdbbeecaf56c093facbac595a Mon Sep 17 00:00:00 2001 From: mhucka Date: Fri, 13 Jun 2025 22:31:19 +0000 Subject: [PATCH 1/5] Adjust and spiff up README format The way sections were arranged in the REAMDE file left lacked hierarchical consistency. In addition, there was not much of an introduction, which could leave new visitors a bit confused. I made the section structure more hierarchical, moved a section or two around for better logical flow, and added the usual badges and other visual elements at the top. --- README.md | 100 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 74 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index e04b3a6d5..d6d9c54e7 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,46 @@ +
+ # qsim and qsimh -Quantum circuit simulators qsim and qsimh. These simulators were used for cross -entropy benchmarking in +High-performance quantum circuit simulators for C++ and Python. + +[![Licensed under the Apache 2.0 +license](https://img.shields.io/badge/License-Apache%202.0-3c60b1.svg?logo=opensourceinitiative&logoColor=white&style=flat-square)](https://github.com/quantumlib/qsim/blob/main/LICENSE) +![C++](https://img.shields.io/badge/C%2B%2B17-fcbc2c.svg?logo=c%2B%2B&logoColor=white&style=flat-square&label=C%2B%2B) +[![qsim project on +PyPI](https://img.shields.io/pypi/v/qsim.svg?logo=python&logoColor=white&label=PyPI&style=flat-square&color=e57430)](https://pypi.org/project/qsim) +[![Compatible with Python versions 3.10 and +higher](https://img.shields.io/badge/Python-3.10+-fcbc2c.svg?style=flat-square&logo=python&logoColor=white)](https://www.python.org/downloads/) +[![Archived in +Zenodo](https://img.shields.io/badge/10.5281%2Fzenodo.4023103-gray.svg?label=DOI&logo=doi&logoColor=white&style=flat-square&colorA=gray&colorB=3c60b1)](https://doi.org/10.5281/zenodo.4023103) + +[Features](#features) – +[Usage](#usage) – +[Documentation](#cirq-documentation) – +[Citing qsim](#citing-qsim) – +[Contact](#contact) + +
+ +_qsim_ and _qsimh_ are Schrödinger and Schrödinger-Feynman state vector +simulators for quantum circuits. They are highly tuned to take advantage of +vector arithmetic instruction sets and multithreading on computers that provide +them, as well as GPUs when available. qsim also provides a +[Cirq](https://quantumai.google/cirq) interface (`qsimcirq`) and can be used to +simulate quantum circuits written in Cirq. These simulators were used to produce +landmark cross-entropy benchmarking results published in Nature [[1]](https://www.nature.com/articles/s41586-019-1666-5). [[1]](https://www.nature.com/articles/s41586-019-1666-5), F. Arute et al, "Quantum Supremacy Using a Programmable Superconducting Processor", Nature 574, 505, (2019). -## qsim +## Features + +qsim and qsimh (yes, they really are spelled in all lower case!) are two +closely-related libraries. They are described in more detail below. + +### qsim qsim is a Schrödinger full state-vector simulator. It computes all the *2n* amplitudes of the state vector, where *n* is the number of qubits. @@ -18,7 +50,7 @@ The total runtime is proportional to *g2n*, where *g* is the number o 2-qubit gates. To speed up the simulator, we use gate fusion [[2]](https://arxiv.org/abs/1601.07195) [[3]](https://arxiv.org/abs/1704.01127), single precision arithmetic, AVX/FMA instructions for vectorization and OpenMP -for multi-threading. +for multithreading on hardware that provides those features. [[2]](https://arxiv.org/abs/1601.07195) M. Smelyanskiy, N. P. Sawaya, A. Aspuru-Guzik, "qHiPSTER: The Quantum High Performance Software Testing @@ -28,7 +60,7 @@ Environment", arXiv:1601.07195 (2016). "0.5 Petabyte Simulation of a 45-Qubit Quantum Circuit", arXiv:1704.01127 (2017). -## qsimh +### qsimh qsimh is a hybrid Schrödinger-Feynman simulator [[4]](https://arxiv.org/abs/1807.10749). The lattice is split into two parts @@ -59,61 +91,77 @@ simulations with different prefix paths and sum the results to get *F = 1*. S. Boixo, "Quantum Supremacy Is Both Closer and Farther than It Appears", arXiv:1807.10749 (2018). -## C++ Usage +## Usage + +### C++ usage The code is basically designed as a library. The user can modify sample applications in [apps](https://github.com/quantumlib/qsim/tree/master/apps) to meet their own needs. The usage of sample applications is described in the [docs](https://github.com/quantumlib/qsim/blob/master/docs/usage.md). +### Python usage + +The Python `qsimcirq` module provides a Python interface to the qsim library. + +### Cirq usage + +[Cirq](https://github.com/quantumlib/cirq) is a framework for modeling and +invoking Noisy Intermediate Scale Quantum (NISQ) circuits. Cirq can use qsim +as its simulation library. To get started with simulating Cirq circuits using +qsim, please refer to the +[tutorial](https://github.com/quantumlib/qsim/blob/master/docs/tutorials/qsimcirq.ipynb). + +More detailed information about the qsim-Cirq API can be found in the +[docs](https://github.com/quantumlib/qsim/blob/master/docs/cirq_interface.md). + ### Input format +> [!NOTE] +> This format is deprecated, and no longer actively maintained. + The circuit input format is described in the [docs](https://github.com/quantumlib/qsim/blob/master/docs/input_format.md). -NOTE: This format is deprecated, and no longer actively maintained. - -### Sample Circuits +### Sample circuits A number of sample circuits are provided in [circuits](https://github.com/quantumlib/qsim/tree/master/circuits). ### Unit tests -Unit tests for C++ libraries use the Google test framework, and are -located in [tests](https://github.com/quantumlib/qsim/tree/master/tests). -Python tests use pytest, and are located in +Unit tests for C++ libraries use the +[GoogleTest](https://github.com/google/googletest) framework, and are located in +[tests](https://github.com/quantumlib/qsim/tree/master/tests). Python tests use +[pytest](https://docs.pytest.org/en/stable/), and are located in [qsimcirq_tests](https://github.com/quantumlib/qsim/tree/master/qsimcirq_tests). To build and run all tests, run: -``` + +```shell make run-tests ``` + This will compile all test binaries to files with `.x` extensions, and run each test in series. Testing will stop early if a test fails. It will also run tests of the `qsimcirq` python interface. To run C++ or python tests only, run `make run-cxx-tests` or `make run-py-tests`, respectively. -To clean up generated test files, run `make clean` from the test directory. +To clean up generated test files, run `make clean` from the test directory -## Cirq Usage +## qsim documentation -[Cirq](https://github.com/quantumlib/cirq) is a framework for modeling and -invoking Noisy Intermediate Scale Quantum (NISQ) circuits. +Please visit the [qsim documentation site](https://quantumai.google/qsim) +guides, tutorials, and API reference documentation. -To get started simulating Google Cirq circuits with qsim, see the -[tutorial](https://github.com/quantumlib/qsim/blob/master/docs/tutorials/qsimcirq.ipynb). -More detailed information about the qsim-Cirq API can be found in the -[docs](https://github.com/quantumlib/qsim/blob/master/docs/cirq_interface.md). - -# How to cite qsim +## How to cite qsim Qsim is uploaded to Zenodo automatically. Click on this badge [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.4023103.svg)](https://doi.org/10.5281/zenodo.4023103) to see all the citation formats for all versions. -An equivalent BibTex format reference is below for all the versions: +An equivalent BibTeX format reference is below for all the versions: -``` +```bibtex @software{quantum_ai_team_and_collaborators_2020_4023103, author = {Quantum AI team and collaborators}, title = {qsim}, @@ -136,7 +184,7 @@ This is not an officially supported Google product. This project is not eligible for the [Google Open Source Software Vulnerability Rewards Program](https://bughunters.google.com/open-source-security). -Copyright 2019 The Cirq Developers. +Copyright 2019 Google LLC.
From b26ae2157ef7ed2124f0678b9feff5655664fbc0 Mon Sep 17 00:00:00 2001 From: mhucka Date: Fri, 13 Jun 2025 22:33:09 +0000 Subject: [PATCH 2/5] Change the note to a warning --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d6d9c54e7..e153ff5da 100644 --- a/README.md +++ b/README.md @@ -117,7 +117,7 @@ More detailed information about the qsim-Cirq API can be found in the ### Input format -> [!NOTE] +> [!WARNING] > This format is deprecated, and no longer actively maintained. The circuit input format is described in the From 12483a59dd687bb0f3a9dec87792c00374522904 Mon Sep 17 00:00:00 2001 From: mhucka Date: Mon, 16 Jun 2025 16:39:40 +0000 Subject: [PATCH 3/5] Remove mention of qsimh & adjust text --- README.md | 111 ++++++++++++++++++++---------------------------------- 1 file changed, 40 insertions(+), 71 deletions(-) diff --git a/README.md b/README.md index e153ff5da..d9bb8c2f2 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@
-# qsim and qsimh +# qsim -High-performance quantum circuit simulators for C++ and Python. +High-performance quantum circuit simulator for C++ and Python. [![Licensed under the Apache 2.0 license](https://img.shields.io/badge/License-Apache%202.0-3c60b1.svg?logo=opensourceinitiative&logoColor=white&style=flat-square)](https://github.com/quantumlib/qsim/blob/main/LICENSE) @@ -22,74 +22,43 @@ Zenodo](https://img.shields.io/badge/10.5281%2Fzenodo.4023103-gray.svg?label=DOI
-_qsim_ and _qsimh_ are Schrödinger and Schrödinger-Feynman state vector -simulators for quantum circuits. They are highly tuned to take advantage of -vector arithmetic instruction sets and multithreading on computers that provide -them, as well as GPUs when available. qsim also provides a -[Cirq](https://quantumai.google/cirq) interface (`qsimcirq`) and can be used to -simulate quantum circuits written in Cirq. These simulators were used to produce -landmark cross-entropy benchmarking results published in Nature -[[1]](https://www.nature.com/articles/s41586-019-1666-5). - -[[1]](https://www.nature.com/articles/s41586-019-1666-5), F. Arute et al, -"Quantum Supremacy Using a Programmable Superconducting Processor", -Nature 574, 505, (2019). - -## Features - -qsim and qsimh (yes, they really are spelled in all lower case!) are two -closely-related libraries. They are described in more detail below. - -### qsim - -qsim is a Schrödinger full state-vector simulator. It computes all the *2n* -amplitudes of the state vector, where *n* is the number of qubits. -Essentially, the simulator performs matrix-vector multiplications repeatedly. -One matrix-vector multiplication corresponds to applying one gate. -The total runtime is proportional to *g2n*, where *g* is the number of -2-qubit gates. To speed up the simulator, we use gate fusion -[[2]](https://arxiv.org/abs/1601.07195) [[3]](https://arxiv.org/abs/1704.01127), -single precision arithmetic, AVX/FMA instructions for vectorization and OpenMP -for multithreading on hardware that provides those features. - -[[2]](https://arxiv.org/abs/1601.07195) M. Smelyanskiy, N. P. Sawaya, -A. Aspuru-Guzik, "qHiPSTER: The Quantum High Performance Software Testing -Environment", arXiv:1601.07195 (2016). - -[[3]](https://arxiv.org/abs/1704.01127) T. Häner, D. S. Steiger, -"0.5 Petabyte Simulation of a 45-Qubit Quantum Circuit", arXiv:1704.01127 -(2017). - -### qsimh - -qsimh is a hybrid Schrödinger-Feynman simulator -[[4]](https://arxiv.org/abs/1807.10749). The lattice is split into two parts -and the Schmidt decomposition is used to decompose 2-qubit gates on the -cut. If the Schmidt rank of each gate is *m* and the number of gates on -the cut is *k* then there are *mk* paths. To simulate a circuit with -fidelity one, one needs to simulate all the *mk* paths and sum the results. - The total runtime is proportional to *(2n1 + 2n2)mk*, where *n1* -and *n2* are the qubit numbers in the first and second parts. Path -simulations are independent of each other and can be trivially parallelized -to run on supercomputers or in data centers. Note that one can run simulations -with fidelity *F < 1* just by summing over a fraction *F* of all the paths. - -A two level checkpointing scheme is used to improve performance. Say, there -are *k* gates on the cut. We split those into three parts: *p+r+s=k*, where -*p* is the number of "prefix" gates, *r* is the number of "root" gates and -*s* is the number of "suffix" gates. The first checkpoint is executed after -applying all the gates up to and including the prefix gates and the second -checkpoint is executed after applying all the gates up to and including the -root gates. The full summation over all the paths for the root and suffix gates -is performed. - -If *p>0* then one such simulation gives *F ≈ m-p* (for all the -prefix gates having the same Schmidt rank *m*). One needs to run *mp* -simulations with different prefix paths and sum the results to get *F = 1*. - -[[4]](https://arxiv.org/abs/1807.10749) I. L. Markov, A. Fatima, S. V. Isakov, -S. Boixo, "Quantum Supremacy Is Both Closer and Farther than It Appears", -arXiv:1807.10749 (2018). +_qsim_ is a state-vector simulator for quantum circuits. It is highly tuned to +take advantage of vector arithmetic instruction sets and multithreading on +computers that provide them, as well as GPUs when available. qsim also provides +a [Cirq](https://quantumai.google/cirq) interface (`qsimcirq`) and can be used +to simulate quantum circuits written in Cirq. + +## Introduction + +qsim is a Schrödinger full state-vector simulator: it models quantum +computations by representing the quantum state of a system as a vector of +complex numbers (a state vector) and evolving it through the application of +quantum gates. One matrix-vector multiplication corresponds to applying one +gate. Essentially, the simulator performs matrix-vector multiplications +repeatedly. + +Being a _full_ state-vector simulator means that qsim computes all the +*2n* amplitudes of the state vector, where *n* is the number of +qubits. The total runtime is proportional to *g2 n*, where *g* is the +number of 2-qubit gates. To speed up the simulator, qsim uses gate fusion +[[1]](#foonote1) [[2]](#foonote1), single-precision arithmetic, and (on +hardware that provides those features) AVX/FMA instructions for vectorization +and OpenMP for multithreading. + +qsim was used to produce landmark cross-entropy benchmarking results +[[3]](#footnote3) published in Nature in 2019. + +[1]: M. Smelyanskiy, N. P. Sawaya, A. Aspuru-Guzik, +"qHiPSTER: The Quantum High Performance Software Testing Environment", +[arXiv:1601.07195](https://arxiv.org/abs/1601.07195) (2016). + +[2]: T. Häner, D. S. Steiger, "0.5 Petabyte Simulation of +a 45-Qubit Quantum Circuit", +[arXiv:1704.01127](https://arxiv.org/abs/1704.01127) (2017). + +[3]: F. Arute et al, "Quantum Supremacy Using a +Programmable Superconducting Processor", [Nature 574, +505](https://www.nature.com/articles/s41586-019-1666-5), (2019). ## Usage @@ -107,7 +76,7 @@ The Python `qsimcirq` module provides a Python interface to the qsim library. ### Cirq usage [Cirq](https://github.com/quantumlib/cirq) is a framework for modeling and -invoking Noisy Intermediate Scale Quantum (NISQ) circuits. Cirq can use qsim +invoking Noisy Intermediate-Scale Quantum (NISQ) circuits. Cirq can use qsim as its simulation library. To get started with simulating Cirq circuits using qsim, please refer to the [tutorial](https://github.com/quantumlib/qsim/blob/master/docs/tutorials/qsimcirq.ipynb). From 49286883418f788830bd07ae3d5866134fb3f27e Mon Sep 17 00:00:00 2001 From: mhucka Date: Wed, 18 Jun 2025 19:18:49 +0000 Subject: [PATCH 4/5] Add more info to the Python installation instructions --- README.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index d9bb8c2f2..5c9f34776 100644 --- a/README.md +++ b/README.md @@ -71,7 +71,24 @@ to meet their own needs. The usage of sample applications is described in the ### Python usage -The Python `qsimcirq` module provides a Python interface to the qsim library. +The qsim-Cirq Python interface is called `qsimcirq` and is available as a PyPI +package for Linux, MacOS and Windows users. It can be installed by using the +following command: + +```shell +pip install qsimcirq +``` + +`qsimcirq` is also available for Conda for Linux and MacOS. To install it from +conda-forge, you can use the following command: + +```shell +conda install -c conda-forge qsimcirq +``` + +_Note_: The core qsim library (located in the source repository under the +[`lib/`](https://github.com/quantumlib/qsim/blob/master/lib) subdirectory) can +be included directly in C++ programs without installing the Python interface. ### Cirq usage From 59a4518b12fee92eea1d7abb64b60834bc0e4b32 Mon Sep 17 00:00:00 2001 From: mhucka Date: Wed, 18 Jun 2025 22:35:42 +0000 Subject: [PATCH 5/5] Inline the references in the intro I found it hard to scan the text in that intro due to the way that the references were formatted. It seems good enough to put them inline, so I did. --- README.md | 37 ++++++++++++++----------------------- 1 file changed, 14 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 5c9f34776..8d207f3e2 100644 --- a/README.md +++ b/README.md @@ -32,33 +32,24 @@ to simulate quantum circuits written in Cirq. qsim is a Schrödinger full state-vector simulator: it models quantum computations by representing the quantum state of a system as a vector of -complex numbers (a state vector) and evolving it through the application of -quantum gates. One matrix-vector multiplication corresponds to applying one -gate. Essentially, the simulator performs matrix-vector multiplications +complex numbers (a _state vector_) and evolving it through the application of +quantum gates. One matrix-vector multiplication corresponds to the application +of one gate. Essentially, the simulator performs matrix-vector multiplications repeatedly. Being a _full_ state-vector simulator means that qsim computes all the -*2n* amplitudes of the state vector, where *n* is the number of +*2 n* amplitudes of the state vector, where *n* is the number of qubits. The total runtime is proportional to *g2 n*, where *g* is the -number of 2-qubit gates. To speed up the simulator, qsim uses gate fusion -[[1]](#foonote1) [[2]](#foonote1), single-precision arithmetic, and (on -hardware that provides those features) AVX/FMA instructions for vectorization -and OpenMP for multithreading. - -qsim was used to produce landmark cross-entropy benchmarking results -[[3]](#footnote3) published in Nature in 2019. - -[1]: M. Smelyanskiy, N. P. Sawaya, A. Aspuru-Guzik, -"qHiPSTER: The Quantum High Performance Software Testing Environment", -[arXiv:1601.07195](https://arxiv.org/abs/1601.07195) (2016). - -[2]: T. Häner, D. S. Steiger, "0.5 Petabyte Simulation of -a 45-Qubit Quantum Circuit", -[arXiv:1704.01127](https://arxiv.org/abs/1704.01127) (2017). - -[3]: F. Arute et al, "Quantum Supremacy Using a -Programmable Superconducting Processor", [Nature 574, -505](https://www.nature.com/articles/s41586-019-1666-5), (2019). +number of 2-qubit gates. To speed up simulation, qsim uses gate fusion +(Smelyanskiy et al., [arXiv:1601.07195](https://arxiv.org/abs/1601.07195), 2016; +Häner and Steiger, [arXiv:1704.01127](https://arxiv.org/abs/1704.01127), 2017), +single-precision arithmetic, AVX/FMA instructions for vectorization, and +OpenMP for multithreading (on hardware that provides those features). + +qsim was used to produce landmark cross-entropy benchmarking results published +in 2019 (Arute et al., "Quantum Supremacy Using a Programmable Superconducting +Processor", [Nature +vol. 574](https://www.nature.com/articles/s41586-019-1666-5), 2019). ## Usage