docs: add MPS simulator documentation (fixes #1048)#1064
Conversation
- Add docs/mps.md: covers what MPS is, MPSStateSpace and MPSSimulator C++ APIs, current limitations, and a comparison table vs qsim/qsimh - Update docs/overview.md: mention MPS as a third simulator alongside qsim and qsimh, add it to the operations list - Update docs/_book.yaml: register mps.md in the Guides nav section Fixes quantumlib#1048
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request adds documentation for the Matrix Product State (MPS) simulator, including a new guide and updates to the navigation and overview files. The review feedback identifies that the C++ code examples in the documentation are missing required template arguments for the MPSStateSpace and MPSSimulator classes, which would cause compilation errors. Additionally, a potential buffer overflow was identified in the reduced density matrix example if double precision is used.
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
mhucka
left a comment
mhucka
left a comment
There was a problem hiding this comment.
Thanks for doing this! I have a bunch of comments but they're all small stuff, plus an open question for the main author of qsim.
I want to note that the new text does have the look of something partly or wholly generated using an LLM. If that's the case, please mention that in the PR description.
| A Matrix Product State is a way of representing a quantum state as a chain of | ||
| tensors, one per qubit, connected together. Instead of storing one giant | ||
| exponentially-large vector, you store a sequence of small matrices. The "bond | ||
| dimension" (often written as χ or `bond_dim`) controls how much entanglement the |
There was a problem hiding this comment.
What is "entanglement" in this context?
| representation can capture: a higher bond dimension is more accurate but uses more | ||
| memory and takes longer to simulate. | ||
|
|
||
| The catch, and the reason this is so useful, is that many quantum circuits of |
There was a problem hiding this comment.
| The catch, and the reason this is so useful, is that many quantum circuits of | |
| The catch, and the reason MPS is so useful, is that many quantum circuits of |
|
|
||
| ## Where to find the implementation | ||
|
|
||
| The MPS simulator lives in two C++ header files: |
There was a problem hiding this comment.
| The MPS simulator lives in two C++ header files: | |
| The qsim MPS simulation interface lives in two C++ header files: |
| When a 2-qubit gate is applied, the simulator: | ||
| 1. Contracts the two neighboring MPS tensors into one combined tensor. | ||
| 2. Applies the gate matrix. | ||
| 3. Uses **Singular Value Decomposition (SVD)** to split the result back into two |
There was a problem hiding this comment.
| 3. Uses **Singular Value Decomposition (SVD)** to split the result back into two | |
| 3. Uses singular value decomposition (SVD) to split the result back into two |
| tensors. | ||
| 4. Keeps only the top `bond_dim` singular values, truncating the rest. | ||
|
|
||
| This is the key step where approximation happens. If the true quantum state |
There was a problem hiding this comment.
Which step does "this" refer to?
| - **Only 1-qubit and 2-qubit gates are supported.** Support for 3+ qubit gates | ||
| is not yet implemented (commented placeholders exist in the source). | ||
| - **Controlled gates are not yet implemented.** `ApplyControlledGate` exists but | ||
| is a stub (`// TODO`). | ||
| - **Expectation values are not yet implemented.** `ExpectationValue` currently | ||
| returns a placeholder value of `(-10, -10)`. | ||
| - **No Python interface.** The MPS simulator is currently only accessible through | ||
| C++. It is not yet exposed via the `qsimcirq` Python package. | ||
| - **2-qubit gates must act on adjacent qubits.** Non-adjacent 2-qubit gates | ||
| require SWAP networks (not handled automatically). |
There was a problem hiding this comment.
Please use emphasis (i.e., single underscores) instead of bold face for the list item styling.
| ## Design | ||
|
|
||
| The git repository for qsim includes two top-level libraries for simulation: | ||
| The git repository for qsim includes three libraries for simulation: |
There was a problem hiding this comment.
I am not sure if the MPS portion should be referred to as a separate library, but we should defer to @sergeisakov 's opinion in this matter. Sergei, do you think of it as a separate library, or is it really just a part of qsim?
Co-authored-by: Michael Hucka <mhucka@google.com>
Co-authored-by: Michael Hucka <mhucka@google.com>
Co-authored-by: Michael Hucka <mhucka@google.com>
Enhanced explanations of matrix product states and their limitations. Clarified the role of bond dimension and approximation in MPS simulation.
Clarify SVD terminology in the MPS documentation.
2 participants
Adds docs/mps.md documenting the MPS simulator in lib/mps_simulator.h
and lib/mps_statespace.h, which had no documentation. Also updates
overview.md and _book.yaml to include it.
The initial draft was generated with LLM assistance(Claude Sonnet 4.6) and then reviewed
and revised based on the source code and maintainer feedback.
Fixes #1048