feature: MPS Encoding Algorithm by ACE07-Sev · Pull Request #179 · amazon-braket/amazon-braket-algorithm-library

ACE07-Sev · 2026-02-16T13:16:40Z

Issue #, if available:#1193

Description of changes:

Added MPS Encoding Algorithm.

Testing done:

Added unit tests for product states, general area-law entangled states, and single qubit states.

Merge Checklist

Put an x in the boxes that apply. You can also fill these out after creating the PR. If you're unsure about any of them, don't hesitate to ask. We're here to help! This is simply a reminder of what we are going to look for before merging your pull request.

General

I have read the CONTRIBUTING doc
I used the commit message format described in CONTRIBUTING
I have updated any necessary documentation, including READMEs and API docs (if appropriate)

Tests

I have added tests that prove my fix is effective or that my feature works (if appropriate)
I have checked that my tests are not configured for a specific region or account (if appropriate)

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

ACE07-Sev · 2026-02-16T13:30:51Z

Some context I think is useful. So, MPS Encoding is the task of doing approximate state preparation using Matrix Product State (MPS) representation of a dense tensor (aka our statevector) as an IR. What happens is we approximate the target state with a MPS, and then compile that MPS to a circuit.

The exponential depth reduction comes from how MPS uses $O(N\chi^2)$ parameters as opposed to $O(N)$ where $\chi$ is the bond dimension (think of it like a knob that you can increase to make the MPS approximation better). Ran's approach uses a compressed bond-2 MPS, so $\chi$ is always equal to 2, and thus by stacking multiple layers of bond 2 MPS we are able to perform the state preparation.

Caveats are that vanilla MPS (what's presented here) only does well on area-law entangled states as that's a limitation of MPS itself. To improve that, I can also make a PR for Application 2 issue where I can add a sweeping algorithm that works both as a standalone circuit optimizer as well as a complementary optimization for MPS.

P.S: I finished preparing the sweeping I mentioned as a PR for application 2. If this PR sees interest, I'll open one for that as well.

sesmart · 2026-02-17T15:17:29Z

Hi @ACE07-Sev, this is really cool! Thanks for the contribution, and would be really cool to see the follow up as well.

Merging from main should fix the readthedocs, though will try and test a PR locally to see what some of the tox issues are.

ACE07-Sev · 2026-02-17T16:07:28Z

Thanks for the contribution, and would be really cool to see the follow up as well.

I'm glad you like it. Sure thing, I should have a PR for that in a bit.

ACE07-Sev · 2026-02-17T16:54:14Z

The coverage issue makes sense. I only tested the behavior of the encoding on different target states, not individual lines of code (more like a black box testing approach).

ACE07-Sev · 2026-02-17T17:28:32Z

@sesmart I added the PR for sweeping #183.

If you like that, I can add the unitary version of sweeping as well.

notebooks/textbook/MPS_Encoding.ipynb

src/braket/experimental/algorithms/mps_encoding/mps_encoding.py

sesmart · 2026-02-20T16:06:56Z

src/braket/experimental/algorithms/mps_encoding/mps_encoding.py

+
+        # Single qubit statevector is optimal, and cannot be
+        # further improved given depth of 1
+        if num_qubits == 1:


I would have this as a new function or include in the main conversion function

So a new function for single qubit state prep?

I think so yes, just to make the call method a bit cleaner. But it's not a big deal. mps_to_circuit_approx by comparison is >100 LOC - though a lot of that is comments.

src/braket/experimental/algorithms/mps_encoding/mps_encoding.py

sesmart · 2026-02-20T16:22:31Z

src/braket/experimental/algorithms/mps_encoding/mps_encoding.py

+                U, _, Vh = np.linalg.svd(unitary)
+                unitary = U @ Vh
+
+                circuit.unitary(matrix=unitary, targets=qubits)


Is there a way to limit the unitary dimension in the layers such that we only have maybe d=4, and then can do a 2q unitary decomposition?

Actually, is that achieved by contracting to a bond dimension =2 system? Or not quite? If so I think we can totally do a 2q decomposition.

The unitary dimension here will always be either 1q or 2q. I imagined in your src you'd route to 2q decomposition if the dimension of unitary is 4x4 or 2x2. If not, yes, definitely can use those instead.

Actually, is that achieved by contracting to a bond dimension =2 system? Or not quite? If so I think we can totally do a 2q decomposition.

Forgot to answer this. Yes, we have the guarantee that it'll only use 1 and 2 qubit unitaries because the bond dimension is 2. Given bond dimension 2^n, we can encode that into a gate with n+1 qubits.

Please let me know where I can get the 1q and 2q decompositions to substitute (although this would be better if you do it natively so that when unitary is 2x2 or 4x4 to use the 1q and 2q decompositions automatically).

Also, the compilation point is a bit more complex, and I am more worried about the topology than the native gate choice. 1 and 2q resynthesis will generally occur, in the Braket compiler or in Qiskit.

To submit on a device simply requires that you don't have Circuit.unitary gates, so expressing it in U3 + CX/CZ is sufficient. To do it really well though you should probably take advantage of device properties in the decomposition, which I think is beyond the current scope, and may change guarantees about depth and compactness. Unless the protocol actually can be laid out in a layer-like structure.

For quick - maybe just reference it? It's good to have as a resource but we don't necessarily need the most performant thing.

No no I meant I could just copy paste that code here. Not to reference it, it's a bit embarrassing of a library for that hehe.

Actually, we do support global phase, just not on devices. If you are just converting without supplying a device, I think it should preserve the phase, right?

I added global_phase to basis gates. Should I remove it? It ran and stopped giving the warnings.

Nope, that looks good. That's exactly why it would happen. If you didn't specify basis sets it would have defaulted to all gates ,which might have included unitary and thus not actually decomposed.

ACE07-Sev · 2026-02-23T06:41:53Z

@sesmart Can I get a review please?

codecov · 2026-02-24T22:40:53Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (3c92423) to head (0f4416c).

Additional details and impacted files

@@            Coverage Diff            @@
##              main      #179   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           30        32    +2     
  Lines         1220      1318   +98     
  Branches       156       168   +12     
=========================================
+ Hits          1220      1318   +98

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

src/braket/experimental/algorithms/mps_encoding/mps_encoding.py

sesmart · 2026-02-26T17:25:46Z

src/braket/experimental/algorithms/mps_encoding/mps_encoding.py

+                U, _, Vh = np.linalg.svd(unitary)
+                unitary = U @ Vh
+
+                circuit.unitary(matrix=unitary, targets=qubits)


Also, for the 1- and 2q decompositions, we are okay to use the qiskit-braket-provider here. You can then run to_braket(unitary, optional args), which should decompress it.

ACE07-Sev · 2026-02-26T22:00:12Z

Anything else I need to do on my side?

sesmart · 2026-02-26T22:12:31Z

Nope, looks good to go! Will follow up shortly.

sesmart · 2026-02-27T17:45:46Z

merging to feature branch for the moment, while we get consensus on how to handle quimb as a dependency - marking #1194 as closed.

sesmart · 2026-02-27T17:52:04Z

Hi @ACE07-Sev, can you please comment on one of the algorithms issues in the BDK? It needs to be assigned but you have to comment first.

MPS Encoding Algorithm

cdb7c47

ACE07-Sev requested a review from a team as a code owner February 16, 2026 13:16

Merge branch 'main' into app-1

f5b14fd

sesmart reviewed Feb 20, 2026

View reviewed changes

ACE07-Sev and others added 2 commits February 21, 2026 23:40

resolved some of the edit requests

6f10805

Merge branch 'main' into app-1

74e9c63

add quimb to dependencies

75268c6

sesmart requested changes Feb 26, 2026

View reviewed changes

resolved requests

0f4416c

sesmart self-requested a review February 27, 2026 17:43

sesmart approved these changes Feb 27, 2026

View reviewed changes

sesmart changed the base branch from main to feature-mps February 27, 2026 17:43

sesmart merged commit 723c085 into amazon-braket:feature-mps Feb 27, 2026
13 checks passed

Conversation

ACE07-Sev commented Feb 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge Checklist

General

Tests

Uh oh!

ACE07-Sev commented Feb 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sesmart commented Feb 17, 2026

Uh oh!

ACE07-Sev commented Feb 17, 2026

Uh oh!

ACE07-Sev commented Feb 17, 2026

Uh oh!

ACE07-Sev commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ACE07-Sev Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ACE07-Sev Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sesmart Feb 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ACE07-Sev commented Feb 23, 2026

Uh oh!

codecov bot commented Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ACE07-Sev commented Feb 26, 2026

Uh oh!

sesmart commented Feb 26, 2026

Uh oh!

sesmart commented Feb 27, 2026

Uh oh!

Uh oh!

sesmart commented Feb 27, 2026

Uh oh!

Reviewers

ACE07-Sev commented Feb 16, 2026 •

edited

Loading

ACE07-Sev commented Feb 16, 2026 •

edited

Loading

ACE07-Sev commented Feb 17, 2026 •

edited

Loading

ACE07-Sev Feb 20, 2026 •

edited

Loading

ACE07-Sev Feb 26, 2026 •

edited

Loading

sesmart Feb 26, 2026 •

edited

Loading

codecov bot commented Feb 24, 2026 •

edited

Loading