Add example and tests for fully yielded Zephyr subgraph search by VolodyaCO · Pull Request #45 · dwavesystems/dwave-experimental

VolodyaCO · 2026-04-01T16:56:52Z

Continuation of dwavesystems/dwave-graphs#261

Adds a routine to find embeddings of Zephyr[m, tp] into Zephyr[m, t] with tp < t.

kevinchern

Added minor questions and comments

kevinchern · 2026-04-01T23:07:05Z

+
+
+def _extract_graph_properties(source: nx.Graph, target: nx.Graph) -> tuple[int, int, int]:
+    """Extract and validate Zephyr graph properties, returning ``(m, tp, t)``.


I suggest something more descriptive rather than variable names, e.g.,

Suggested change

"""Extract and validate Zephyr graph properties, returning ``(m, tp, t)``.

"""Extract and validate Zephyr graph properties (rows, tile count, and target tile count).

kevinchern · 2026-04-01T23:11:36Z

+        tuple[int, int, int]: ``(m, tp, t)`` where ``m`` is rows,
+            ``tp`` is source tile count, and ``t`` is target tile count.


Suggested change

tuple[int, int, int]: ``(m, tp, t)`` where ``m`` is rows,

``tp`` is source tile count, and ``t`` is target tile count.

tuple[int, int, int]: source Zephyr rows, source tile count, and target tile count.

kevinchern · 2026-04-01T23:12:38Z

+
+    Raises:
+        TypeError: If metadata values are not integers.
+        ValueError: If graph metadata is missing or incompatible.


I this should detail what it means to be incompatible; incompatibility is implied by ValueError, e.g., positive int or ...

kevinchern · 2026-04-02T02:53:10Z

+            for n in _source.nodes()
+            if n in working_embedding
+        )
+    else:


Suggested change

else:

elif yield_type == "edges":

# do stuff

else:

raise ValueError("blah blah")

I recommend being explicit about checking yield type.

Edit: maybe this is fine since validity of yield type has been validated previously...

Other two options are edge and rail-edge. This is fine, as you say, because the type has been validated.

kevinchern · 2026-04-02T03:05:59Z

+YieldType = Literal["node", "edge", "rail-edge"]
+QuotientSearchType = Literal["by_quotient_rail", "by_quotient_node", "by_rail_then_node"]


Question!!
I think most of these are only ever used in type-hinting. Should we still define these constant type hints here? Is there a best-practice or principle that recommends this pattern?
Subjectively, I find it less readable than writing the types out explicitly in the type hints.

cc @thisac

Yep. in vscode all it takes is to hover over the constant type hint and it will show more details, though.

Type-aliases are good when not overused. I agree with @kevinchern that it can make code less readable. With that said, I'm fine with these, except perhaps Embedding, EmbeddingChain since they're not very clearly named.

kevinchern · 2026-04-02T03:09:33Z

+__all__ = ["zephyr_quotient_search"]
+
+ZephyrNode = tuple[int, int, int, int, int]  # (u, w, k, j, z) coordinate tuple
+Embedding = dict[ZephyrNode, ZephyrNode]  # Internal single-node format


Note for considering a different name: dwave.embedding has an EmbeddedStructure class. Might be worth following that pattern but tailored for Zephyr. e.g., ZephyrEmbeddedStructure (ok maybe this is too long lol)

This Embedding is just a short-hand typing tool. The EmbeddedStructure is a bit more convoluted.

kevinchern · 2026-04-02T15:43:12Z

+
+    pruned_embedding = {
+        to_source(k): to_target(v) for k, v in working_embedding.items() if v in target_nodeset
+    }  # TODO:?: why would a target node in the working_embedding not be in the target_nodeset?


@VolodyaCO has this question been addressed with @jackraymond ?

It hasn't AFAIR.

to_target is an identity, so we can remove it right?

Perhaps its required because you want to cast it to a ZephyrNode, and we can't be sure that's the format provided - the function name could be changed and type hinting improved?

SebastianGitt

Looks good! Just have some minor comments.

SebastianGitt · 2026-04-02T18:32:58Z

+    tiles. It is designed for defective targets where a direct identity map may lose
+    nodes or edges.
+
+    The search is organised around the **quotient graph** of the Zephyr topology, formed by


Suggested change

The search is organised around the **quotient graph** of the Zephyr topology, formed by

The search is organized around the **quotient graph** of the Zephyr topology, formed by

minor issue but US English should be used

Oh I will have a bunch of these. thanks

SebastianGitt · 2026-04-02T18:55:37Z

+    # Phase 1: uniform random deletion
+    n_uniform = round(proportion * uniform_proportion * N)
+    uniform_indices = rng.choice(N, size=n_uniform, replace=False)
+    deleted = {all_nodes[i] for i in uniform_indices}


consider renaming this to something more clear

Changed to deleted_nodes.

SebastianGitt · 2026-04-02T20:45:02Z

+    """Validate that source and target are Zephyr NetworkX graphs.
+
+    Both source and target graphs must be networkx graph instances with a 'family' metadata key
+    set to 'zephyr'. Each graph must also contain 'rows', 'tile' and 'labels metadata keys.


Suggested change

set to 'zephyr'. Each graph must also contain 'rows', 'tile' and 'labels metadata keys.

set to 'zephyr'. Each graph must also contain 'rows', 'tile' and 'labels' metadata keys.

SebastianGitt · 2026-04-02T20:45:32Z

+        if expand_boundary_search:
+            if w == 0:
+                ksymmetric = False
+                # brrow candidates from adjacent internal column


Suggested change

# brrow candidates from adjacent internal column

# borrow candidates from adjacent internal column

SebastianGitt · 2026-04-02T20:46:05Z

+        \{(u, w_t, k_t, j, z) : j \in \{0,1\},\ z \in \{0,\dots,m-1\}\}.
+
+    We can define its objective for ``yield_type='edge'`` as the number of edges preserved within
+    that rail, i.e., the numbe of edges in the target subgraph induced by the proposed rail, or


Suggested change

that rail, i.e., the numbe of edges in the target subgraph induced by the proposed rail, or

that rail, i.e., the number of edges in the target subgraph induced by the proposed rail, or

SebastianGitt · 2026-04-02T20:46:43Z

+
+        F_q = \{m \in V(S) \setminus B_q : m \in \operatorname{dom}(\phi)\},
+
+    where :math:`\phi` is the current embedding`. Then


Suggested change

where :math:`\phi` is the current embedding`. Then

where :math:`\phi` is the current embedding. Then

SebastianGitt · 2026-04-02T20:48:47Z

+
+    Args:
+        quotient_search (str): Search mode.
+        yield_type (str): Optimization objective.


Suggested change

yield_type (str): Optimization objective.

yield_type (YieldType): Optimization objective.

This should be a str, as it validates the search parameters. If it is not a YieldType, then an error is raised.

SebastianGitt · 2026-04-02T20:49:07Z

+            :math:`w` is at a boundary. Defaults to ``True``.
+        ksymmetric (bool): If ``True``, treat source :math:`k` order as interchangeable when scoring
+            rails. Defaults to ``False``.
+        yield_type (str): ``"node"``, ``"edge"``, or ``"rail-edge"``. Defaults to ``"edge"``.


Suggested change

yield_type (str): ``"node"``, ``"edge"``, or ``"rail-edge"``. Defaults to ``"edge"``.

yield_type (YieldType): ``"node"``, ``"edge"``, or ``"rail-edge"``. Defaults to ``"edge"``.

done, thanks

SebastianGitt · 2026-04-02T21:03:39Z

+)
+
+
+def _validate_graph_inputs(source: nx.Graph, target: nx.Graph):


Suggested change

def _validate_graph_inputs(source: nx.Graph, target: nx.Graph):

def _validate_graph_inputs(source: nx.Graph, target: nx.Graph) -> None:

SebastianGitt · 2026-04-02T21:10:52Z

+    ZephyrSearchMetadata, zephyr_quotient_search)
+
+
+def generate_faulty_zephyr_graph(m, t, proportion, uniform_proportion, seed=None):


consider adding type hinting here since this function is non-trivial and used in multiple places

Added type hinting

kevinchern

Did a few passes with focus on usability and some design patterns 🚀

jackraymond

On top of reviews by Sebastian/Kevin:

Check imports, to_target().

A couple of other comments.

Great job

jackraymond · 2026-04-24T21:40:01Z

+
+    pruned_embedding = {
+        to_source(k): to_target(v) for k, v in working_embedding.items() if v in target_nodeset
+    }  # TODO:?: why would a target node in the working_embedding not be in the target_nodeset?


to_target is an identity, so we can remove it right?

jackraymond · 2026-04-24T21:40:53Z

+
+    pruned_embedding = {
+        to_source(k): to_target(v) for k, v in working_embedding.items() if v in target_nodeset
+    }  # TODO:?: why would a target node in the working_embedding not be in the target_nodeset?


Perhaps its required because you want to cast it to a ZephyrNode, and we can't be sure that's the format provided - the function name could be changed and type hinting improved?

jackraymond · 2026-04-24T21:45:36Z

+from minorminer.utils.parallel_embeddings import find_sublattice_embeddings
+
+import dwave_networkx as dnx
+from dwave_networkx.generators._zephyr_playground import zephyr_quotient_search


Requires correction, this won't run

Corrected. Thanks for noticing!

jackraymond · 2026-04-24T21:47:13Z

+    if target.graph["labels"] != "coordinate":
+        raise ValueError("target graph has unknown labelling scheme")
+
+    def to_target(n: ZephyrNode) -> ZephyrNode:


to_target is an identity. Is it really necessary? Is it necessary to caste non-ZephyrNode to ZephyrNode for example? If so the type hint is incorrect.

This to_target is an identity because the case where the graph is not in coordinate labels has already been handled by previous logic. The case where the graph is already in coordinate labels, this function needs to be an identity.

Is this ever something other than just an identity? Otherwise I still don't see this as doing anything.

jackraymond · 2026-04-24T21:49:54Z

+        working_embedding: Embedding = {n: n for n in source_nodes}
+    else:
+        # Convert chain format to internal single-node format
+        working_embedding = {k: v[0] for k, v in embedding.items()}


Do we need to check a few things here?

Should we check there is a key for every source node? If it is absent throw an error that a key is missing in the candidate (and document requirement)

Check the length of all values is 1.

these are both checked in _validate_search_parameters and _ensure_coordinate_source.

jackraymond · 2026-04-24T21:57:46Z

+    This routine starts from a source Zephyr graph with ``m`` rows and ``tp`` tiles,
+    and maps it into a target Zephyr graph with the same ``m`` rows and ``t >= tp``
+    tiles. It is designed for defective targets where a direct identity map may lose
+    nodes or edges.


I think we should highlight limitations at the end of this first paragraph:

"Since a greedy method is used for embedding search, it is possible it fails to find a 1:1 embedding where one is viable. A complete method such as :code:minorminer.subgraph.find_subgraph may be more appropriate in a scenario such as this, especially with customization of parameters to the target families. Similarly, when defect rates are high direct use of :code: minorminer.find_embedding may be a more efficient strategy."

I'm teeing up the other module I'd like to add here which is find_subgraph enhanced by S,T pair specific node_labels.

jackraymond · 2026-04-25T00:23:14Z

I'd like to pair this module with a tool that uses source and target graph specific knowledge to accelerate find_subgraph(). This tool is not zephyr specific, but it would be good if it could be placed alongside this tool. For this reason, could we consider relabeling the subdirectory as 'embedding_methods' rather than 'zephyr_embedding_methods' (less specific), or perhaps 'processor_graph_embedding_methods' (if we wanted to be more specific)

…en updated when an incomplete source was provided. Clarify that the zephyr_quotient_embedding_search is a greedy method and has limitations in the docstrings. Co-authored-by: Copilot <copilot@github.com>

VolodyaCO · 2026-04-27T17:31:32Z

@jackraymond the example has been updated and runs correctly as expected.

Co-authored-by: Copilot <copilot@github.com>

…on during the example. Co-authored-by: Copilot <copilot@github.com>

jackraymond

LGTM

jackraymond · 2026-04-25T00:19:30Z

+import networkx as nx
+import numpy as np
+from dwave_networkx import zephyr_graph
+from dwave_networkx.generators._zephyr_playground import (


This is a bad import

thisac

Might be good to check out dwavesystems/dwave-graphs#266 and coordinate with @mahdiehmalekian, specifically with regards to some of the zephyr utility functions and checks.

I'll have a closer look at the main zephyr_quotient_search function and tests.

thisac · 2026-04-27T21:39:42Z

+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from .zephyr_quotient_embedding_search import *


Recommended to use absolute imports instead of relative.

thisac · 2026-04-27T21:47:53Z

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


Since this will likely be moved over to dwave-graphs at some point, and there's already a ZephyrCoord tuple-like being added there, it's probably good to coordinate a bit and make sure that these two are compatible.

thisac · 2026-04-27T21:48:33Z

+__all__ = ["zephyr_quotient_search"]
+
+ZephyrNode = tuple[int, int, int, int, int]  # (u, w, k, j, z) coordinate tuple
+Embedding = dict[ZephyrNode, ZephyrNode]  # Internal single-node format


Seems simple enough to just keep dict[ZephyrNode, ZephyrNode] as the type.

thisac · 2026-04-27T21:56:34Z

+YieldType = Literal["node", "edge", "rail-edge"]
+QuotientSearchType = Literal["by_quotient_rail", "by_quotient_node", "by_rail_then_node"]


Type-aliases are good when not overused. I agree with @kevinchern that it can make code less readable. With that said, I'm fine with these, except perhaps Embedding, EmbeddingChain since they're not very clearly named.

thisac · 2026-04-27T23:36:25Z

+    if embedding is not None and not isinstance(embedding, dict):
+        raise TypeError(f"embedding must be a dictionary when provided. Got {type(embedding)}")
+    if embedding is not None:


One less check.

Suggested change

if embedding is not None and not isinstance(embedding, dict):

raise TypeError(f"embedding must be a dictionary when provided. Got {type(embedding)}")

if embedding is not None:

if embedding is not None:

if not isinstance(embedding, dict):

raise TypeError(f"embedding must be a dictionary when provided. Got {type(embedding)}")

thisac · 2026-04-27T23:42:25Z

+    Returns:
+        tuple[nx.Graph, set[ZephyrNode], Callable[[ZephyrNode], int | ZephyrNode]]:
+            ``(_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 space.


Shouldn't be indented on returns. Also, could remove all types in docstrings since type-hints are used.

thisac · 2026-04-27T23:46:48Z

+                "graph, along with any other missing nodes.", UserWarning
+            )
+            _source.add_nodes_from(source_nodes)
+            breakpoint()


Leftover from debugging?

Suggested change

breakpoint()

thisac · 2026-04-27T23:47:44Z

+    # If the labels are coordinate. Then we just return the graph as is and the identity function
+    # for to_source:
+
+    def to_source(n: ZephyrNode) -> ZephyrNode:
+        return n


I don't really see the point of this?

thisac · 2026-04-27T23:48:15Z

+        tuple[nx.Graph, Callable[[ZephyrNode], int | ZephyrNode]]:
+            ``(_target, to_target)`` where ``_target`` is coordinate-labelled.


Remove indentation.

thisac · 2026-04-27T23:51:40Z

+    if target.graph["labels"] != "coordinate":
+        raise ValueError("target graph has unknown labelling scheme")
+
+    def to_target(n: ZephyrNode) -> ZephyrNode:


Is this ever something other than just an identity? Otherwise I still don't see this as doing anything.

Add example and tests for fully yielded Zephyr subgraph search

c18cc51

VolodyaCO mentioned this pull request Apr 1, 2026

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

Closed

thisac requested review from SebastianGitt, jackraymond and kevinchern April 1, 2026 21:38

kevinchern reviewed Apr 7, 2026

View reviewed changes

SebastianGitt approved these changes Apr 7, 2026

View reviewed changes

Improve documentation of parameters and type hinting

e1bec8f

kevinchern approved these changes Apr 8, 2026

View reviewed changes

jackraymond suggested changes Apr 24, 2026

View reviewed changes

Correct relative import in init. Warn the user that the source has be…

51f8846

…en updated when an incomplete source was provided. Clarify that the zephyr_quotient_embedding_search is a greedy method and has limitations in the docstrings. Co-authored-by: Copilot <copilot@github.com>

Vladimir Vargas Calderón and others added 2 commits April 27, 2026 17:38

Correct imports

7e90ec7

Co-authored-by: Copilot <copilot@github.com>

Improve print statements so that the user knows more about what goes …

f366c39

…on during the example. Co-authored-by: Copilot <copilot@github.com>

jackraymond approved these changes Apr 27, 2026

View reviewed changes

thisac reviewed Apr 27, 2026

View reviewed changes



		def _extract_graph_properties(source: nx.Graph, target: nx.Graph) -> tuple[int, int, int]:
		"""Extract and validate Zephyr graph properties, returning ``(m, tp, t)``.

		tuple[int, int, int]: ``(m, tp, t)`` where ``m`` is rows,
		``tp`` is source tile count, and ``t`` is target tile count.

	tuple[int, int, int]: ``(m, tp, t)`` where ``m`` is rows,
	``tp`` is source tile count, and ``t`` is target tile count.
	tuple[int, int, int]: source Zephyr rows, source tile count, and target tile count.

-    else:
+    elif yield_type == "edges":
+        # do stuff
+    else:
+        raise ValueError("blah blah")

		YieldType = Literal["node", "edge", "rail-edge"]
		QuotientSearchType = Literal["by_quotient_rail", "by_quotient_node", "by_rail_then_node"]

	The search is organised around the quotient graph of the Zephyr topology, formed by
	The search is organized around the quotient graph of the Zephyr topology, formed by

	set to 'zephyr'. Each graph must also contain 'rows', 'tile' and 'labels metadata keys.
	set to 'zephyr'. Each graph must also contain 'rows', 'tile' and 'labels' metadata keys.

	# brrow candidates from adjacent internal column
	# borrow candidates from adjacent internal column

	that rail, i.e., the numbe of edges in the target subgraph induced by the proposed rail, or
	that rail, i.e., the number of edges in the target subgraph induced by the proposed rail, or


		F_q = \{m \in V(S) \setminus B_q : m \in \operatorname{dom}(\phi)\},

		where :math:`\phi` is the current embedding`. Then

	yield_type (str): Optimization objective.
	yield_type (YieldType): Optimization objective.

	yield_type (str): ``"node"``, ``"edge"``, or ``"rail-edge"``. Defaults to ``"edge"``.
	yield_type (YieldType): ``"node"``, ``"edge"``, or ``"rail-edge"``. Defaults to ``"edge"``.

		)


		def _validate_graph_inputs(source: nx.Graph, target: nx.Graph):

		ZephyrSearchMetadata, zephyr_quotient_search)


		def generate_faulty_zephyr_graph(m, t, proportion, uniform_proportion, seed=None):


		__all__ = ["zephyr_quotient_search"]

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

		tuple[nx.Graph, Callable[[ZephyrNode], int \| ZephyrNode]]:
		``(_target, to_target)`` where ``_target`` is coordinate-labelled.

Conversation

VolodyaCO commented Apr 1, 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!

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!

SebastianGitt 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!

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