Add Rabi Oscillations textbook notebook by friedsam · Pull Request #188 · amazon-braket/amazon-braket-algorithm-library

friedsam · 2026-02-27T22:38:29Z

*Issue #, if available:*Originally prepared in relation to amazon-braket-sdk-python#1194

Description of changes:
This PR adds a Rabi Oscillations example to the Amazon Braket Algorithm Library.

The contribution includes:

New utility functions rabi_probability, rabi_circuit, rabi_simulated_dynamics, and excited_state_probability under src/braket/experimental/algorithms/rabi_oscillations/
Unit tests validating the new utilities
A textbook notebook Rabi_Oscillations.ipynb demonstrating:
- Theoretical background and analytic expression for ( P(|1\rangle) )
- Exact simulator results using shots=0
- Finite-shot sampling comparison
- T1 relaxation using a single damping channel
- Stepwise T1 relaxation during driven evolution
- A comparison between single-channel and stepwise T1 models
- Stepwise T2 dephasing during driven evolution
- Combined T1 and T2 noise during driven evolution
- Off-resonant Rabi oscillations using detuning
- Off-resonant Rabi oscillations with T1 and T2 noise
An updated README entry referencing the new notebook

No existing core functionality was modified.

Testing done:

•	tox -e unit-tests

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.

friedsam · 2026-03-23T21:16:35Z

Thanks for updating the branch. Please let me know if any further changes or documentation updates are needed from my side. Thanks again for reviewing the notebook.

peterkomar-aws · 2026-03-24T17:41:41Z

Hi @friedsam , thanks for this contribution. This is a great idea for the textbook algorithm collection; it aligns with its educational direction (see Bell inequality). We are happy to add this if you could enrich it with 2-3 more demonstrations (in the same notebook is fine) that show how the effect of noise (T1, T2) can be simulated with Braket noisy circuits, and how the dynamics of off-resonant Rabi oscillation can be encoded with single qubit rotations, and maybe all of them combined. The circuits and the graphs will be more complex and will give the reader a good learning experience without going beyond the initial scope, i.e. Rabi oscillation. Also, happy to give more guidance on what part of the Braket Python SDK may be useful for this demo. What do you think?

friedsam · 2026-03-24T20:58:22Z

Hi Peter, thanks a lot for the detailed feedback — that’s very helpful!
I like the idea of expanding the notebook in that direction and adding demonstrations for T1/T2 noise as well as off-resonant Rabi oscillations and a combined comparison.
It may take me a some time to work through these additions and structure the new sections properly. But I’ll update the notebook accordingly and will make sure that this still happens in a timely manner.
If you have any specific Braket SDK features you would recommend for the noise modeling part, I’d be happy to take a look.
Thanks again for the guidance!

peterkomar-aws · 2026-03-25T13:24:01Z

Wonderful! Thanks for the quick response. For noise simulation the Simulating_Noise_On_Amazon_Braket.ipynb notebook is a great place to start. Let us know if you hit any blocker.

friedsam · 2026-03-28T04:35:48Z

Thank you very much for the pointer to the Simulating_Noise_On_Amazon_Braket notebook — that’s very helpful.
I hope I will get to this over the weekend or soon after and will come back to you.
Thanks again for the guidance!

…tinuous damping

…ations

friedsam · 2026-04-21T22:42:33Z

Thanks again for the guidance. I’ve now updated the notebook to include T1 and T2 noise models, combined T1+T2 noisy dynamics, off-resonant Rabi oscillations, and an off-resonant example with T1 and T2 noise. I also reran the unit tests and rebased onto the latest upstream main. Please let me know if you’d like any further adjustments.

codecov · 2026-04-24T02:54:58Z

Codecov Report

❌ Patch coverage is 30.76923% with 27 lines in your changes missing coverage. Please review.
✅ Project coverage is 98.28%. Comparing base (2424037) to head (fdc5926).

Files with missing lines	Patch %	Lines
.../algorithms/rabi_oscillations/rabi_oscillations.py	27.02%	27 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##              main     #188      +/-   ##
===========================================
- Coverage   100.00%   98.28%   -1.72%     
===========================================
  Files           34       36       +2     
  Lines         1535     1574      +39     
  Branches       200      208       +8     
===========================================
+ Hits          1535     1547      +12     
- Misses           0       27      +27

☔ 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.

review-notebook-app · 2026-04-24T18:48:21Z

Check out this pull request on

See visual diffs & provide feedback on Jupyter Notebooks.

Powered by ReviewNB

sesmart · 2026-04-24T19:45:36Z

@@ -0,0 +1,1042 @@
+{


T1 is not generally measured under driven evolution, so I honestly am not sure I quite follow this part. If you still want to consider it as a time evolving system, then maybe it makes sense to start in the X basis and make an X-measurement?

Reply via ReviewNB

Reworded this section to clarify that the single damping channel is a simple circuit-level amplitude-damping demonstration, not a full time-resolved T1 experiment.

Okay, I understand the confusion now, and that is more helpful - maybe we can change the first sentence to something like "We first model our two level system undergoing a Rabi oscillation under T1 relaxation".

Updated the wording in the T1 introduction accordingly.

sesmart · 2026-04-24T19:45:36Z

@@ -0,0 +1,1042 @@
+{


See earlier comment.

Reply via ReviewNB

sesmart · 2026-04-24T19:45:36Z

@@ -0,0 +1,1042 @@
+{


You definitely don't need to repeat the probability generating function everytime if you have a singular processing function.

Reply via ReviewNB

sesmart · 2026-04-24T19:45:36Z

@@ -0,0 +1,1042 @@
+{


This is nice, and it might be cool to show what the one-time application looks like versus a discretized evolution.

Reply via ReviewNB

Added a direct comparison plot between single-channel damping and stepwise T1 evolution to highlight the difference.

sesmart · 2026-04-24T19:45:36Z

@@ -0,0 +1,1042 @@
+{


Might make sense to even have a matrix here that shows detuning versus the driving frequency, and how that relates to X and Z rotations.

Reply via ReviewNB

Added a table linking detuning and drive parameters to their corresponding X and Z rotations in the circuit model.

sesmart · 2026-04-24T19:45:36Z

@@ -0,0 +1,1042 @@
+{


I don't think you need this at all.

Reply via ReviewNB

Removed the tracker section to keep the notebook focused on the core physical and circuit concepts.

sesmart · 2026-04-24T19:47:22Z

Hi @friedsam, thank you for following up! I think overall the direction and content are much more suitable now. I have made some suggestions related to consolidating code and improving certain explanations, please let me know if you have any questions.

friedsam · 2026-05-06T00:45:49Z

Thanks again for the detailed feedback and suggestions — they were very helpful. I updated the notebook accordingly, including the code consolidation changes, revised explanations, updated plots, and the additional comparison/discussion sections. I also reran the notebook and unit tests after the updates, and everything now executes successfully.

sesmart · 2026-05-07T21:28:51Z

@@ -0,0 +1,902 @@
+{


Line #4. def rabi_demo_circuit(
This is great, and I think captures basically all of the logic - let's move this function into the rabi_oscillation file; could just name it as rabi_simulated_dynamics or something similar, and then expand on the description and arguments there. I'm also not sure why you allow for arbitrary arguments? Not necessary here.

I would also add a run method, that encapsulates the probability simulations you use to run the circuit, and allows for shots or no shots.

Reply via ReviewNB

I moved the reusable helper logic into the rabi_oscillations source module as rabi_simulated_dynamics and added an excited_state_probability helper so the notebook no longer defines these locally.

sesmart · 2026-05-07T21:28:51Z

@@ -0,0 +1,902 @@
+{


Line #49. def probability_of_one(circ: Circuit, device: LocalSimulator) -> float:
I would rename this function - excited_state_probability is fine. As it is used extensively throughout it can be the referenced function above.

Reply via ReviewNB

sesmart · 2026-05-07T21:28:51Z

@@ -0,0 +1,902 @@
+{


So, here the time delta is constant right? 0.1? Is the right way to think of the gamma <-> angle relation as a fixed gamma subdivided into more and more chunks? So in the single channel case, there is no angle / time relation, it just is just applied to one single chunk and that's why we don't see an angle variance.

I'm not sure I quite understand what the take away is here - could you clarify it a little bit? To show that a once-only-model is wrong? This is somewhat of a discretization problem, as in a time-based picture you would implement the stepwise damping strength could either be gamma * theta, or in a stepwise picture, dt * gamma over t/dt steps.

I guess this plot is showing the discretization error of N=1, over a large range of theta, versus increasing N (by fixing theta=0.1)? Could use a little more detail regardless.

Reply via ReviewNB

I expanded this section to better distinguish the single-channel damping example from the stepwise approximation to relaxation during the driven evolution.

sesmart · 2026-05-07T21:28:51Z

@@ -0,0 +1,902 @@
+{


Let's put a similar note here - noting that we are adding T2 dephasing to our noise model.

Reply via ReviewNB

I updated the T2 section with analogous clarification.

sesmart · 2026-05-07T21:28:51Z

@@ -0,0 +1,902 @@
+{


Nice, this is very helpful.

Reply via ReviewNB

Glad the table was helpful — I thought it would make the detuning picture more explicit at the circuit level.

sesmart · 2026-05-22T17:43:06Z

Hi @friedsam , the current state looks much better - I think that last remaining big item is to update tests to improve coverage. Let me know if there are any issues with that. Thanks!

friedsam · 2026-06-09T01:50:51Z

I added tests for the new helper functions rabi_simulated_dynamics and excited_state_probability. I reran the unit test suite successfully: 144 passed, 7 xfailed, 1 warning.

friedsam requested a review from a team as a code owner February 27, 2026 22:38

friedsam added 5 commits April 21, 2026 17:23

feat: add Rabi oscillations textbook notebook, utilities, and tests

ec057ad

Add T1 relaxation models to Rabi oscillations notebook

20a770f

Use constant step size in stepwise T1 model to better approximate con…

3e14023

…tinuous damping

Add T2 and combined T1+T2 noisy Rabi simulations

8930c7d

Complete Rabi oscillations notebook with noisy and off-resonant simul…

aaa7181

…ations

friedsam force-pushed the add-rabi-oscillations branch from 9934171 to aaa7181 Compare April 21, 2026 21:25

Finalize Rabi oscillations notebook

1ce458a

sesmart reviewed Apr 24, 2026

View reviewed changes

Refine Rabi oscillations notebook based on review feedback

9330ec3

Merge branch 'main' into add-rabi-oscillations

8a6f91b

sesmart reviewed May 7, 2026

View reviewed changes

Refactor reusable Rabi dynamics helpers

fdc5926

Add tests for Rabi dynamics helpers

49553cd

Conversation

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

Uh oh!

Merge Checklist

General

Tests

Uh oh!

friedsam commented Mar 23, 2026

Uh oh!

peterkomar-aws commented Mar 24, 2026

Uh oh!

friedsam commented Mar 24, 2026

Uh oh!

peterkomar-aws commented Mar 25, 2026

Uh oh!

friedsam commented Mar 28, 2026

Uh oh!

friedsam commented Apr 21, 2026

Uh oh!

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

Uh oh!

Codecov Report

Uh oh!

review-notebook-app Bot commented Apr 24, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sesmart Apr 24, 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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sesmart Apr 24, 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 Apr 24, 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 Apr 24, 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!

sesmart Apr 24, 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!

sesmart Apr 24, 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!

sesmart commented Apr 24, 2026

Uh oh!

friedsam commented May 6, 2026

Uh oh!

sesmart May 7, 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!

sesmart May 7, 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

friedsam commented Feb 27, 2026 •

edited

Loading

codecov Bot commented Apr 24, 2026 •

edited

Loading

sesmart Apr 24, 2026 •

edited

Loading

sesmart Apr 24, 2026 •

edited

Loading

sesmart Apr 24, 2026 •

edited

Loading

sesmart Apr 24, 2026 •

edited

Loading

sesmart Apr 24, 2026 •

edited

Loading

sesmart Apr 24, 2026 •

edited

Loading

sesmart May 7, 2026 •

edited

Loading

sesmart May 7, 2026 •

edited

Loading

sesmart May 7, 2026 •

edited

Loading

sesmart May 7, 2026 •

edited

Loading

sesmart May 7, 2026 •

edited

Loading