Routine to find zephyr[m,tp] in possibly-faulty zephyr[m,t] with tp < t by VolodyaCO · Pull Request #261 · dwavesystems/dwave-graphs

VolodyaCO · 2026-03-12T22:54:04Z

This PR adds a heuristic routine written by @jackraymond to find an embedding from a source graph zephyr[m, tp] to a target graph which is a subgraph of zephyr[m,t]. The motivation of this routine is to have a tool to generate zephyr subgraphs that are resilient to possible future qubit/coupler defects in actual QPUs.

Tests are added to make sure that the routine indeed improves the yield of the embedded graph.

kevinchern

Nice work Jack&Vlad 🤩!! I did a quick first pass with mostly minor suggestions.

kevinchern · 2026-03-13T16:51:49Z

dwave_networkx/generators/_zephyr_playground.py

@@ -0,0 +1,914 @@
+# Copyright 2026 D-Wave Systems Inc.


Suggested change

# Copyright 2026 D-Wave Systems Inc.

# Copyright 2026 D-Wave

and other occurrences

Other headers in the files have the full name:
https://github.com/dwavesystems/dwave-networkx/blob/main/dwave_networkx/generators/zephyr.py#L1

Should I keep the full name?

Only change for new files is the policy.

Keeping name short

kevinchern · 2026-03-13T16:53:58Z

dwave_networkx/generators/_zephyr_playground.py

+
+from dwave_networkx import zephyr_coordinates, zephyr_graph
+
+ZephyrNode = tuple[int, int, int, int, int]  # (u, w, k, j, z) coordinate tuple


Does something similar exist in dnx? @mahdiehmalekian @thisac

Will exist in near future.

kevinchern · 2026-03-13T16:55:35Z

dwave_networkx/generators/_zephyr_playground.py

+ZephyrNode = tuple[int, int, int, int, int]  # (u, w, k, j, z) coordinate tuple
+Embedding = dict[ZephyrNode, ZephyrNode]
+YieldType = Literal["node", "edge", "rail-edge"]
+KSearchType = Literal["by_quotient_rail", "by_quotient_node", "by_rail_then_node"]


Is there a more descriptive name for "K"? (if not, consider adding a comment explaining what K refers to)

This is for @jackraymond

It's not currently an informative name.
Per literal options, QuotientSearchType might be good, and we have to be careful to describe the 'quotient graph' in docs.

kevinchern · 2026-03-13T16:59:45Z

dwave_networkx/generators/_zephyr_playground.py

+
+
+def _validate_graph_inputs(source: nx.Graph, target: nx.Graph) -> tuple[int, int, int]:
+    """Validate Zephyr graph compatibility and return ``(m, tp, t)``.


Can we describe the checklist of requirements? e.g., inputs are required to be networkx graphs.

I just added it.

kevinchern · 2026-03-13T17:02:44Z

dwave_networkx/generators/_zephyr_playground.py

+        TypeError: If inputs are not NetworkX graphs.
+        ValueError: If graph metadata is missing or incompatible.
+    """
+    if not isinstance(source, nx.Graph) or not isinstance(target, nx.Graph):


I think we don't require them to be networkx graphs ~~and we'll be moving away from networkx~~.
~~That said, this is fine; just a heads-up~~

edit: ^^^ this is partially incorrect 😅. We're not moving away from networkx, but probably don't require this input to be a networkx graph

kevinchern · 2026-03-13T17:38:39Z

dwave_networkx/generators/_zephyr_playground.py

+            ``(_source, source_nodes, to_source)`` where ``_source`` is
+            coordinate-labelled, ``source_nodes`` is the full canonical coordinate
+            node set implied by ``m`` and ``tp``, and ``to_source`` maps
+            coordinate nodes back to the original source labelling spcae.


Suggested change

coordinate nodes back to the original source labelling spcae.

coordinate nodes back to the original source labelling space.

Thanks for catching this!

kevinchern · 2026-03-13T17:43:29Z

dwave_networkx/generators/_zephyr_playground.py

+) -> tuple[nx.Graph, Callable[[ZephyrNode], int | ZephyrNode]]:
+    """Return a coordinate-labelled target graph and conversion callable.
+
+    This is similar to the source version but does not need to return the full canonical node set


I would add a standalone description before contrasting with the source version

Ok, I've added this.

kevinchern · 2026-03-13T17:53:18Z

dwave_networkx/generators/_zephyr_playground.py

+    ksymmetric: bool = False,
+    yield_type: YieldType = "edge",
+) -> tuple[dict, dict | None, ZephyrSearchMetadata]:
+    r"""Compute a high-yield Zephyr-to-Zephyr  embedding.


Suggested change

r"""Compute a high-yield Zephyr-to-Zephyr embedding.

r"""Compute a high-yield Zephyr-to-Zephyr embedding.

😜

kevinchern · 2026-03-13T17:57:19Z

dwave_networkx/generators/_zephyr_playground.py

+    Returns:
+        tuple[dict, dict | None, ZephyrSearchMetadata]:
+            ``(subgraph_embedding, minor_embedding, metadata)``
+            ``subgraph_embedding`` is a pruned one-to-one node map ``source_node -> target_node``.


Can we make the returned embeddings consistent in the sense that the one-to-one embeddings are length-1 chains, e.g., emb[1] == (53,) instead of emb[1] == 53?

cc @jackraymond

We can perhaps add an as_embedding option to match find_subgraph, and default it to True

If it is always assumed that one-to-one embeddings always map nodes to chains (of one node), then I would ensure that the input embedding is also given in this format, and I wouldn't add the as_embedding flag; by default all embeddings would embed to chains.

kevinchern · 2026-03-13T17:59:34Z

dwave_networkx/generators/_zephyr_playground.py

+            ``source_node -> tuple[target_nodes, ...]`` or ``None``. If the greedy search did not
+            achieve full yield and minorminer is disabled, or minorminer was not able to find an
+            embedding, then ``minor_embedding`` is ``None``. If full yield is achieved, then


I think this interface can be naturally split in two functions. Currently, it attempts to A) embed with one method, and tries B) minorminer with a seeded solution when the first fails. Would having the two functions A and B work? This current function can still exist, just as a wrapper that calls A and B in succession.

one minor problem or consideration with my suggestion: validation would step would be required in both procedures A and B. Chaining them would result in redundant validation steps.

Why would we separate the minorminer part? It only uses find_embedding straight-forwardly. What I mean is that if a user wants to use find_embedding to improve a current embedding, all that needs to be done is to use find_embedding directly using the initial_chains argument.

Ah wait that's a good point. In that case, I think it's better to remove it altogether for modularity's sake. This would simplify the dependencies and nested arguments.

jackraymond · 2026-03-16T17:36:32Z

Embedding helpers are more often added to minorminer these days, would that not be the correct location? dwave-experimental is another option.

This pull-request fails (testing) because dwave-networkx does not (and should not) depend on minorminer.
This is an embedding helper function, not a wrapper for networkx, so I think it should be moved to minorminer in the medium term, and perhaps dwave-experimental in the short term (flexibility to change defaults and signatures may be useful).

jackraymond · 2026-03-16T20:07:03Z

With a view to related functionality, I'd prefer this module were called something like processor_sublattice_embeddings.py and have the module located at ~/GIT/minorminer/minorminer/utils

jackraymond · 2026-03-16T19:50:24Z

dwave_networkx/generators/_zephyr_playground.py

+    Returns:
+        tuple[dict, dict | None, ZephyrSearchMetadata]:
+            ``(subgraph_embedding, minor_embedding, metadata)``
+            ``subgraph_embedding`` is a pruned one-to-one node map ``source_node -> target_node``.


We can perhaps add an as_embedding option to match find_subgraph, and default it to True

jackraymond · 2026-03-16T20:11:17Z

dwave_networkx/generators/_zephyr_playground.py

+import minorminer
+import networkx as nx
+import numpy as np
+from dwave.embedding import is_valid_embedding, verify_embedding


We don't want to add dwave as a dwave_networkx dependency. Maybe move pull request to minorminer/utils (per other comment).

jackraymond · 2026-03-16T20:11:34Z

dwave_networkx/generators/_zephyr_playground.py

+from collections import namedtuple
+from typing import Callable, Literal, get_args
+
+import minorminer


We don't want to add mionrminer as a dwave_networkx dependency. Maybe move pull request to minorminer/utils (per other comment).

@jackraymond I just realized the only dependence on minorminer is find_embedding. Is the method feasible if we passed in a embedding_function and embedding_function_kwargs as arguments for the more general approach?

nvm; this is utility is closer to embeddings than it is to graphs, and it still has dependency on dwave for other functions like validating/verifying embeddings. more reasons to be in minorminer than dnx.

jackraymond · 2026-03-16T20:20:24Z

dwave_networkx/generators/_zephyr_playground.py

+    return pruned_embedding, embedding2, metadata
+
+
+def main(


Move to examples/

I would actually get rid of this. Most of what is in the main function is already in the tests. I just didn't delete it the first time. An useful example for me would be to take an existing qpu graph and use the zephyr_quotient_search function to get a fully-yielded Zephyr subgraph. I believe this is what we are building this tool for. However, from the report cards, the unyielded qubits (either nodes or couplers) seem to agglutinate, which means that for a real qpu graph there are no valid zephyr subgraphs with the same number of columns m.

I agree, better to delete than to move.

At yield rates on current Adv2 processors subgraph isomorphisms (for any tp) can be verified as non-existent. If we fully randomize the location of node failures this remains true (with high probability), so agglutination is not the only challenge. But that would be the correct direction for an example.

jackraymond · 2026-03-16T20:20:52Z

dwave_networkx/generators/_zephyr_playground.py

+
+
+if __name__ == "__main__":
+    solver_names = ["Advantage2_system1.11", "Advantage2_system1.12"]


Move to examples, and perhaps default to any zephyr solver through the client. Can also allow non-client option that uses MockDwaveSampler.

jackraymond · 2026-03-16T20:50:08Z

dwave_networkx/generators/_zephyr_playground.py

+    else:
+        fn = f"{solver_name}.pkl"
+        if not os.path.isfile(fn):
+            qpu = DWaveSampler(profile="defaults", solver=solver_name)


Suggested change

qpu = DWaveSampler(profile="defaults", solver=solver_name)

qpu = DWaveSampler(solver=solver_name)

jackraymond

We will need to move this to minorminer or dwave-experimental

Mostly looks good. But will require second round review.

Ran tests and examples. I will try to test performance of this (greedy) method relative to our slower complete methods (per internal research).

Validate that an input embedding is indeed a one-to-one mapping. Explain thoroughly yield types in the docstrings of the relevant functions. Fix typos in the docstrings.

VolodyaCO

Went through the code comments and pushed fixes. Left questions in some of the comments too.

VolodyaCO · 2026-03-16T15:59:38Z

dwave_networkx/generators/_zephyr_playground.py

+
+
+def _validate_graph_inputs(source: nx.Graph, target: nx.Graph) -> tuple[int, int, int]:
+    """Validate Zephyr graph compatibility and return ``(m, tp, t)``.


Even though the user can extract m, tp and t, they can always be obtained from the source and target graphs, so returning these numbers avoids a potential error of the user entering the wrong numbers.

VolodyaCO · 2026-03-16T16:01:16Z

dwave_networkx/generators/_zephyr_playground.py

+    if target.graph.get("family") != "zephyr":
+        raise ValueError("target graph should be a zephyr family graph")
+
+    for graph_name, graph in zip(("source", "target"), (source, target)):


I've always thought of zip as a natural function for these sort of things... any reason to avoid it?

VolodyaCO · 2026-03-16T22:09:40Z

dwave_networkx/generators/_zephyr_playground.py

@@ -0,0 +1,914 @@
+# Copyright 2026 D-Wave Systems Inc.


Keeping name short

VolodyaCO · 2026-03-16T22:17:01Z

dwave_networkx/generators/_zephyr_playground.py

+)
+
+
+def _validate_graph_inputs(source: nx.Graph, target: nx.Graph) -> tuple[int, int, int]:


I can first validate that the graph's family exist and are valid, and that the graph's row, tile and labels fields exist to be able to extract these properties. Then, another function would validate these properties. Does that sound good?

VolodyaCO · 2026-03-16T22:27:42Z

dwave_networkx/generators/_zephyr_playground.py

+
+
+def _validate_graph_inputs(source: nx.Graph, target: nx.Graph) -> tuple[int, int, int]:
+    """Validate Zephyr graph compatibility and return ``(m, tp, t)``.


I just added it.

VolodyaCO · 2026-03-18T16:42:05Z

dwave_networkx/generators/_zephyr_playground.py

+    ksymmetric: bool = False,
+    yield_type: YieldType = "edge",
+) -> tuple[dict, dict | None, ZephyrSearchMetadata]:
+    r"""Compute a high-yield Zephyr-to-Zephyr  embedding.


VolodyaCO · 2026-03-18T16:54:20Z

dwave_networkx/generators/_zephyr_playground.py

+        ksearch (KSearchType): Search strategy. One of ``'by_quotient_rail'``,
+            ``'by_quotient_node'``, or ``'by_rail_then_node'``. Defaults to ``'by_quotient_rail'``.


The ksearch strategies are already explained in the docstrings. We can go for shorter names, but I think the longer name may be more informative (as, e.g., the epxression ksearch='by_quotient_node' looks close to what the expression would mean in natural language).

VolodyaCO · 2026-03-18T17:49:30Z

dwave_networkx/generators/_zephyr_playground.py

+    Returns:
+        tuple[dict, dict | None, ZephyrSearchMetadata]:
+            ``(subgraph_embedding, minor_embedding, metadata)``
+            ``subgraph_embedding`` is a pruned one-to-one node map ``source_node -> target_node``.


If it is always assumed that one-to-one embeddings always map nodes to chains (of one node), then I would ensure that the input embedding is also given in this format, and I wouldn't add the as_embedding flag; by default all embeddings would embed to chains.

VolodyaCO · 2026-03-18T17:52:06Z

dwave_networkx/generators/_zephyr_playground.py

+            ``source_node -> tuple[target_nodes, ...]`` or ``None``. If the greedy search did not
+            achieve full yield and minorminer is disabled, or minorminer was not able to find an
+            embedding, then ``minor_embedding`` is ``None``. If full yield is achieved, then


Why would we separate the minorminer part? It only uses find_embedding straight-forwardly. What I mean is that if a user wants to use find_embedding to improve a current embedding, all that needs to be done is to use find_embedding directly using the initial_chains argument.

VolodyaCO · 2026-03-18T17:58:57Z

dwave_networkx/generators/_zephyr_playground.py

+    return pruned_embedding, embedding2, metadata
+
+
+def main(


I would actually get rid of this. Most of what is in the main function is already in the tests. I just didn't delete it the first time. An useful example for me would be to take an existing qpu graph and use the zephyr_quotient_search function to get a fully-yielded Zephyr subgraph. I believe this is what we are building this tool for. However, from the report cards, the unyielded qubits (either nodes or couplers) seem to agglutinate, which means that for a real qpu graph there are no valid zephyr subgraphs with the same number of columns m.

VolodyaCO · 2026-03-18T18:06:53Z

As per moving this PR to minorminer, I do agree. Should we finish this first revision and then close the PR here and open it in minorminer?

jackraymond · 2026-03-20T22:20:00Z

dwave_networkx/generators/_zephyr_playground.py

+            ``max_num_yielded``, ``starting_num_yielded``, and ``final_num_yielded``.
+    """
+
+    m, tp, t = _validate_graph_inputs(source, target)


We should probably allow for source graphs smaller than target graphs, i.e. any combination mp<=m, tp<=t

The simplest (sufficient) way to to do this is to check every sublattice:

best_tuple = None for gen in zephyr_sublattice_mappings(S, T): # This method could be made more efficient by reuse of information on overlapping mappings proposal = zephyr_quotient_search(T=mask(T, gen), *other_kwargs ) if is_better(best_tuple, proposal): best_tuple = proposal if is_optimal: break return best_tuple

Maybe better: when mp <m we advise people to use this embedding method in combination with minorminer.find_sublattice_embeddings (rather than rewriting the same method in special case).

Add and test routine to find zephyr[m,tp] in zephyr[m,t] with tp < t

fc99499

thisac requested a review from kevinchern March 13, 2026 16:51

kevinchern reviewed Mar 14, 2026

View reviewed changes

jackraymond reviewed Mar 16, 2026

View reviewed changes

jackraymond suggested changes Mar 16, 2026

View reviewed changes

Describe validation requirements in docstrings of validation functions.

be3c650

Validate that an input embedding is indeed a one-to-one mapping. Explain thoroughly yield types in the docstrings of the relevant functions. Fix typos in the docstrings.

VolodyaCO commented Mar 18, 2026

View reviewed changes

jackraymond reviewed Mar 20, 2026

View reviewed changes


		from dwave_networkx import zephyr_coordinates, zephyr_graph

		ZephyrNode = tuple[int, int, int, int, int] # (u, w, k, j, z) coordinate tuple



		def _validate_graph_inputs(source: nx.Graph, target: nx.Graph) -> tuple[int, int, int]:
		"""Validate Zephyr graph compatibility and return ``(m, tp, t)``.

	coordinate nodes back to the original source labelling spcae.
	coordinate nodes back to the original source labelling space.

	r"""Compute a high-yield Zephyr-to-Zephyr embedding.
	r"""Compute a high-yield Zephyr-to-Zephyr embedding.



		if __name__ == "__main__":
		solver_names = ["Advantage2_system1.11", "Advantage2_system1.12"]

	qpu = DWaveSampler(profile="defaults", solver=solver_name)
	qpu = DWaveSampler(solver=solver_name)

		ksearch (KSearchType): Search strategy. One of ``'by_quotient_rail'``,
		``'by_quotient_node'``, or ``'by_rail_then_node'``. Defaults to ``'by_quotient_rail'``.

Conversation

VolodyaCO commented Mar 12, 2026

Uh oh!

kevinchern left a comment

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!

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!

kevinchern Mar 13, 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!

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!

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!

jackraymond commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jackraymond commented Mar 16, 2026

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!

kevinchern Mar 16, 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

kevinchern Mar 13, 2026 •

edited

Loading

jackraymond commented Mar 16, 2026 •

edited

Loading

kevinchern Mar 16, 2026 •

edited

Loading