Add Python script to approximate filtered h-gain waveform by qwriter · Pull Request #387 · dwavesystems/dwave-ocean-sdk

qwriter · 2025-09-22T22:50:36Z

This PR includes the following updates:

Add Python script that approximates h-gain waveforms filtered by the Advantage and Advantage2 system's low-pass filters.
For better visibility of setting time-dependent gain for qubit biases, move much of the content from the description of the h_gain_schedule solver parameter to a new section in the QPU annealing topic.
Remove note stating that the h_gain_schedule solver parameter is experimental only.
Add references to papers that set time-dependent gain for qubit biases.

Question: Does the footnote about the supported slope still apply? (see this comment.)

The HTML for the h_gain_schedule solver parameter is here.

The HTML for the new section is here.

JoelPasvolsky

Comment made before you switched to draft. Will review in full once it becomes a non-draft PR again.

docs/quantum_research/solver_parameters.rst

docs/quantum_research/annealing.rst

JoelPasvolsky · 2025-09-29T16:27:42Z

docs/quantum_research/annealing.rst

+==============================================
+
+Time-dependent gain for qubit biases can be used with the standard-anneal
+protocol and reverse annealing ([Vod2025]_, [Pel2023]_).


This introductory sentence starts off with (non)limitations on the feature instead of what the feature is. Compare for example with the nice intro sentence in Pel2023:

We standardly start with an intro that gives the why of a feature rather than the how, and should do so here too.

JoelPasvolsky · 2025-09-29T16:47:01Z

docs/quantum_research/annealing.rst

+
+Time-dependent gain for qubit biases can be used with the standard-anneal
+protocol and reverse annealing ([Vod2025]_, [Pel2023]_).
+The :ref:`parameter_qpu_h_gain_schedule` parameter is applied to qubit


There are two alternatives for feature descriptions in the Annealing Implementation and Controls that seem to me to follow good practices:

Single source these details

Refer users to h-gain-schedule parameter for the details; e.g., "For details on how to set h-gain for a problem, see the h-gain-schedule parameter"

Having two copies of these details, here and under h-gain-schedule parameter, risks discrepancies and adds maintenance costs.

Currently the Varying the Global Anneal Schedule section follows alternative 1, single sourcing the details with the anneal_schedule parameter. I actually think alternative 2 is better: the Annealing Implementation and Controls should explain what these features are used for and provide technical implementation details while the Solver Parameters section should specify usage rules. The former is for learning about the features and its hardware; the latter is a reference page for programmers.

JoelPasvolsky · 2025-09-29T17:08:02Z

docs/quantum_research/annealing.rst

+
+Approximating the Filtered h-gain Waveform
+------------------------------------------
+


The first sentence under this section (or a sentence before this section) needs to explain why we're talking about a filtered waveform:

The I/O system that delivers the h-controlling waveform to a QPU limits bandwidth using a low-pass filter; if you configure a too-rapidly changing curve, even within the supported bounds, expect distorted values of h for your problem

JoelPasvolsky · 2025-09-29T19:54:45Z

docs/quantum_research/annealing.rst

+Approximating the Filtered h-gain Waveform
+------------------------------------------
+
+In this sample Python script, the method ``approximate_filtered_h_gain``


Consider the following structure for this section (rough draft). My concern with the current structure is that we have a very long section taken up with code to produce information unneeded by most researchers reading the Annealing Implementation and Controls, which is the critical physics page. To me it makes sense that for the occasional researcher who needs to get the filtered waveform, they can open a dropdown for the code.

QPU-Executed Schedule

A sentence here about how the input (nominal) schedule is filtered by the I/O and so the schedule executed on the QPU is bandwidth limited, as shown in the figure below.

You can use the provided script to approximate the schedule executed on the QPU.

.. dropdown:: Approximating the Filtered h-gain Waveform Here comes the script.

docs/quantum_research/annealing.rst

docs/quantum_research/solver_parameters.rst

JoelPasvolsky · 2025-09-29T21:04:35Z

docs/quantum_research/annealing.rst

+    >>> from scipy import signal
+    >>> import warnings
+    >>>
+    >>> def approximate_filtered_h_gain (pwl, bandwidth):


Forgot: we should make a PR to add this function to dwave-system, and once that is in the SDK, we would just refer to it here.

randomir · 2025-12-05T12:42:56Z

docs/quantum_research/annealing.rst

+            sampling_rate = int(bandwidth * 100)
+            time_array = np.linspace(t_i, t_f, int(np.ceil(sampling_rate * (t_f - t_i))))
+            sig = np.interp(time_array, pwl[:, 0], pwl[:, 1])
+            b, a = signal.bessel(2, 2/100, btype="lowpass", analog=False, output="ba", norm="mag")


Is this filter consistent with what's actually used, or it's just for illustrative purposes? Different filter types and design choices produce quite different results.

JoelPasvolsky

Almost there

Also, you should rebase to fix the build errors

docs/quantum_research/annealing.rst

JoelPasvolsky · 2026-01-29T17:22:13Z

docs/quantum_research/annealing.rst

+Varying the Linear-Bias Schedule 
+================================
+
+For more control of the annealing process, you can schedule the time-dependent


A couple of thoughts:

"For more control of the annealing process" --> is this clause adding anything helpful?

"schedule the time-dependent" --> here, before it is defined, the non-definite article makes more sense

Basically, I'm suggesting "You can schedule a time-dependent gain for the Hamiltonian's linear biases (i.e., qubit biases)" is shorter without loss of info.

docs/bibliography.rst

JoelPasvolsky · 2026-01-29T17:28:58Z

docs/quantum_research/annealing.rst

+gain for qubit biases can be used with the standard annealing and reverse
+annealing protocols ([Vod2025]_, [Pel2023]_). The


This section would be stronger if the two use cases are moved to the end, something like:

"For examples of using this feature, see [Vod2025]_ and [Pel2023]_ "

docs/quantum_research/annealing.rst

JoelPasvolsky · 2026-01-29T18:52:35Z

docs/quantum_research/annealing.rst

+
+.. _approximate_filtered_h_gain:
+
+.. dropdown:: Approximating the Filtered h-gain Waveform


Here too, instead of the new "h-gain" term, why not "Approximating the Filtered Waveform" or "Approximating the Filtered Gain Waveform" or "Approximating the Gain Applied on the QPU" or many other options?

JoelPasvolsky · 2026-01-29T18:53:29Z

docs/quantum_research/annealing.rst

+    that is filtered and executed on the QPU. The script's
+    ``approximate_filtered_h_gain`` method derives an approximation of the
+    filtered h-gain waveform by applying a second-order low-pass Bessel filter
+    to the input waveform.


Same comments as previously to this intro

docs/quantum_research/annealing.rst

… documentation

Co-authored-by: Joel Pasvolsky <34041130+JoelPasvolsky@users.noreply.github.com>

qwriter marked this pull request as draft September 22, 2025 23:35

JoelPasvolsky self-requested a review September 22, 2025 23:52

JoelPasvolsky reviewed Sep 23, 2025

View reviewed changes

docs/quantum_research/solver_parameters.rst Outdated Show resolved Hide resolved

docs/quantum_research/solver_parameters.rst Show resolved Hide resolved

qwriter self-assigned this Sep 25, 2025

qwriter marked this pull request as ready for review September 25, 2025 22:07

qwriter requested review from ehoskinson and fionahanington September 25, 2025 22:07

JoelPasvolsky reviewed Sep 29, 2025

View reviewed changes

qwriter requested a review from dwave-msamani October 15, 2025 00:52

qwriter force-pushed the doc-712 branch 3 times, most recently from 5340a80 to c684414 Compare November 6, 2025 01:34

randomir reviewed Dec 5, 2025

View reviewed changes

JoelPasvolsky reviewed Jan 29, 2026

View reviewed changes

qwriter force-pushed the doc-712 branch from 6160cab to d3030df Compare January 29, 2026 19:32

qwriter and others added 14 commits February 2, 2026 14:25

Add waveform-filtering simulator code for h_gain_schedule parameter's…

7fe81ca

… documentation

Edit description; format code samples; add code sample that uses method

da34625

Edit for clarity and test sample code

86f20e5

Remove extraneous info; clarify terminology

7799f87

Clarify terminology; reformat and edit

d10e9c6

Move content to a better location

e8de73d

Make h_gain_schedule content more visible by moving it to a new section

0886e15

Add paper citation

98ec956

Clarify note and move to annealing section

c282ddc

Add back footnote and clarify auto-scale usage

29bc9c5

Apply suggestion from @JoelPasvolsky: Edit title

950dccc

Co-authored-by: Joel Pasvolsky <34041130+JoelPasvolsky@users.noreply.github.com>

Apply suggestion from @JoelPasvolsky: Streamline and update code sample

8231204

Co-authored-by: Joel Pasvolsky <34041130+JoelPasvolsky@users.noreply.github.com>

Implement feedback, mainly reorganization

40d4fa7

Add replacement text back into solver parameters topic

8e39eec

qwriter and others added 4 commits February 2, 2026 14:25

Edit content

6c070ff

Fix xref

1117709

Correct to 6.5 Mhz

686f7de

Apply suggestions from code review

5f92f26

Co-authored-by: Joel Pasvolsky <34041130+JoelPasvolsky@users.noreply.github.com>

qwriter force-pushed the doc-712 branch from b0827ac to 5f92f26 Compare February 2, 2026 22:25

Correct units abbreviation

a51f22a


		Approximating the Filtered h-gain Waveform
		------------------------------------------

		gain for qubit biases can be used with the standard annealing and reverse
		annealing protocols ([Vod2025]_, [Pel2023]_). The


		.. _approximate_filtered_h_gain:

		.. dropdown:: Approximating the Filtered h-gain Waveform

Conversation

qwriter commented Sep 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

JoelPasvolsky left a comment

Choose a reason for hiding this comment

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!

Choose a reason for hiding this comment

QPU-Executed Schedule

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!

JoelPasvolsky left a comment • 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!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

qwriter commented Sep 22, 2025 •

edited

Loading

JoelPasvolsky left a comment •

edited

Loading