results: register defaults, YieldHandling key formats, and root exports by qci-amos · Pull Request #76 · dwavesystems/dwave-gate

qci-amos · 2026-08-19T16:55:00Z

Part of splitting #71 into reviewable pieces. This is the non-QCDL half —
dwave.gate.results — and is independent of the other four PRs.

Three independent fixes, one commit each.

1. `get_memory` / `get_counts` default to the measured register

Both fell back to get_default_register, which lists every qubit in the
circuit whether or not it was measured. An unmeasured qubit was therefore
padded into the bitstring with unmeasured_value and read as an outcome:
a three-qubit circuit measuring only q1 and q2 returned {"01_": 3}.

They now default to get_measurements_register, falling back to every qubit
only when nothing was measured at all. get_default_register is unchanged and
still available — pass it explicitly to get the padded register back — and its
docstring now says which methods use it and when.

Compatibility: this changes the default output shape for any circuit with
unmeasured qubits. Callers passing an explicit register are unaffected.

2. `YieldHandling.apply` handles every counts key format

apply tested keys with "*" not in k. count_measurements(..., key_format=None)
produces integer keys, so composing the two — which is the obvious thing to
do — raised TypeError: argument of type 'int' is not iterable. The
all-erasures fallback had the same assumption, building its zeros key with
str.replace.

Only the string key formats can hold a splat, so the erasure test now checks
for that, and the fallback key falls back to 0 for a non-string key.

An empty distribution raised StopIteration out of that fallback, which is not
a useful error for a counts dict that post-selection emptied; it now raises
ValueError.

apply also picked up the docstring it never had.

3. Export `Result` and `YieldHandling` from the package root

The user guide refers to these as dwave.gate.Result and
dwave.gate.YieldHandling, which did not resolve. They are re-exported from
the package root and remain importable from dwave.gate.results, which is
still where they are defined — a test asserts __module__ does not move, since
Sphinx and pickle both key off it.

Testing

pytest tests/ passes. tests/test_results.py covers the register default
(including the explicit-register and nothing-measured paths), apply against
every key format count_measurements produces, and the import paths.

🤖 Generated with Claude Code

Both fell back to get_default_register, which lists every qubit in the circuit whether or not it was measured, so an unmeasured qubit was padded into the bitstring and read as an outcome. They now default to get_measurements_register and fall back to every qubit only when nothing was measured at all. Passing get_default_register explicitly still gets the padded register. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

apply() tested keys with `"*" not in k`, which raises TypeError on the integer keys count_measurements produces for key_format=None, and built its all-erasures fallback key with str.replace. Only string keys can hold a splat, so the erasure test now checks for that and the fallback key falls back to 0 for a non-string key. An empty distribution raised StopIteration from the fallback, which is not a useful error for a counts dict that post selection emptied; it now raises ValueError. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

The user guide refers to these as dwave.gate.Result and dwave.gate.YieldHandling, which did not resolve. They are re-exported from the package root and remain importable from dwave.gate.results, which is still where they are defined, so __module__ does not move. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

codecov · 2026-08-19T16:55:15Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.71%. Comparing base (2b82b20) to head (82076a9).

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #76      +/-   ##
==========================================
+ Coverage   90.18%   90.71%   +0.53%     
==========================================
  Files          31       31              
  Lines        5317     5377      +60     
==========================================
+ Hits         4795     4878      +83     
+ Misses        522      499      -23

☔ View full report in Codecov by Harness.
📢 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.

JoelPasvolsky · 2026-08-20T20:01:13Z

+
+        Only the string key formats can hold a splat: the
+        :func:`.count_measurements` function produces integer keys only for
+        memory that is entirely 0s and 1s.


wouldn't splay be held as -1? Maybe not here.

What's at stake here are the data types that count_measurements can return. The key_format there may be bin, hex, and None. Maybe we should remove hex and None, I don't know of any current use of those (count_measurements was written before erasures).

But regardless, hex and "integer" for keys don't support splats. We only have -1 outside of a bitstring context or * for a bitstring context.

That said, I can imagine that at scale we'll want some representation more compact than strings... but we're not at the point where that matters yet and Qiskit requires strings afaik.

JoelPasvolsky · 2026-08-20T20:03:00Z

+            :exception:`ValueError`: If the distribution is empty, or if the
+                yield is too low for
+                :attr:`.renormalize_distribution_or_raise`.
+            :exception:`ZeroDivisionError`: If nothing survives post selection


Is this the best error type for this case?

It's raised here:

dwave-gate/dwave/gate/results.py

Line 711 in 5d1f965

raise ZeroDivisionError("yield is zero, can't renormalize distribution")

I generally try to use the built-in types where it makes sense and it seems like this qualifies: there really is a "divide by zero" that would occur here. We could do a custom error if that's what you mean?

I think I meant that our code should prevent an known divide-by-zero error if it's caused by a bad user input (not allow such an input) or a bad calculation on our part (return some message that there are insufficient samples or some such).
If it means a big change to the application, I don't have a preference for a custom error. See what makes sense to you

The cause of this could be a circuit that's too deep or wide. So it's not that the input is "bad" in a validation sense nor a bug in the qpu/simulator.

We've debated in the past whether this case should be a log message (that might be missed) or a raised exception and we've gone with the later because otherwise downstream logic (e.g., qiskit) might raise their own less-informative exception if they receive an empty bitstring distribution.

thisac · 2026-09-01T21:47:17Z

+# The user guide refers to these as dwave.gate.Result and
+# dwave.gate.YieldHandling, so re-export them from the package root. They remain
+# importable from dwave.gate.results, which is where they are defined.


This comment doesn't really add any value.

Suggested change

# The user guide refers to these as dwave.gate.Result and

# dwave.gate.YieldHandling, so re-export them from the package root. They remain

# importable from dwave.gate.results, which is where they are defined.

thisac · 2026-09-01T21:57:19Z

+            # A qubit with no measurements has no bit to contribute, and padding
+            # one in makes the bitstring look like an outcome. Fall back to every
+            # qubit only when nothing was measured at all.
+            register = cast(RegisterType, self.get_measurements_register(tag)) or None


It might be correct to use here, but I really don't like typing.cast.

Is it even needed here? RegisterType is just list[str | None] and self.get_measurements_register() returns list[str].

thisac · 2026-09-01T22:22:13Z

+# ---------------------------------------------------------------------------
+# Documented import paths
+# ---------------------------------------------------------------------------
+
+
+def test_result_classes_are_importable_from_the_package_root():
+    """The guide refers to these as dwave.gate.Result / dwave.gate.YieldHandling."""
+    import dwave.gate
+
+    assert dwave.gate.Result is Result
+    assert dwave.gate.YieldHandling is YieldHandling
+    assert set(dwave.gate.__all__) == {"Result", "YieldHandling"}
+
+
+def test_re_export_leaves_the_defining_module_alone():
+    """Sphinx and pickle both key off __module__, so it must not move."""
+    assert Result.__module__ == "dwave.gate.results"
+    assert YieldHandling.__module__ == "dwave.gate.results"
+
+


I would probably skip these tests since we're not usually testing every single import or namespace. Seems a bit excessive.

qci-amos and others added 3 commits August 19, 2026 12:51

qci-amos requested review from JoelPasvolsky, randomir and thisac August 19, 2026 18:33

JoelPasvolsky approved these changes Aug 20, 2026

View reviewed changes

qci-amos added 2 commits August 25, 2026 10:27

Merge branch 'main' into results/api-defaults-and-key-handling

bf1f8c3

reno note

82076a9

thisac reviewed Sep 1, 2026

View reviewed changes

Navigation Menu

Uh oh!

results: register defaults, YieldHandling key formats, and root exports - #76

results: register defaults, YieldHandling key formats, and root exports#76
qci-amos wants to merge 5 commits into
mainfrom
results/api-defaults-and-key-handling

qci-amos commented Aug 19, 2026

Uh oh!

codecov Bot commented Aug 19, 2026 •

edited

Loading

Uh oh!

JoelPasvolsky Aug 20, 2026

Uh oh!

qci-amos Aug 25, 2026

Uh oh!

qci-amos Aug 25, 2026

Uh oh!

JoelPasvolsky Aug 20, 2026

Uh oh!

qci-amos Aug 25, 2026

Uh oh!

JoelPasvolsky Sep 1, 2026

Uh oh!

qci-amos Sep 1, 2026

Uh oh!

Uh oh!

Uh oh!

thisac Sep 1, 2026

Uh oh!

thisac Sep 1, 2026

Uh oh!

thisac Sep 1, 2026

Uh oh!

thisac Sep 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	# The user guide refers to these as dwave.gate.Result and
	# dwave.gate.YieldHandling, so re-export them from the package root. They remain
	# importable from dwave.gate.results, which is where they are defined.

Uh oh!

Conversation

qci-amos commented Aug 19, 2026

1. get_memory / get_counts default to the measured register

2. YieldHandling.apply handles every counts key format

3. Export Result and YieldHandling from the package root

Testing

Uh oh!

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

Uh oh!

Codecov Report

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!

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!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

1. `get_memory` / `get_counts` default to the measured register

2. `YieldHandling.apply` handles every counts key format

3. Export `Result` and `YieldHandling` from the package root

codecov Bot commented Aug 19, 2026 •

edited

Loading