def embed_bqm(source_bqm,
embedding=None,
target_adjacency=None,
chain_strength=None,
smear_vartype=None):
"""Embed a binary quadratic model onto a target graph.
Args:
source_bqm (:class:`~dimod.BinaryQuadraticModel`):
Binary quadratic model to embed.
embedding (dict/:class:`.EmbeddedStructure`):
Mapping from source graph to target graph as a dict of form
{s: {t, ...}, ...}, where s is a source-model variable and t is a
target-model variable. Alternately, an EmbeddedStructure object
produced by, for example,
EmbeddedStructure(target_adjacency.edges(), embedding). If embedding
is a dict, target_adjacency must be provided.
target_adjacency (dict/:obj:`networkx.Graph`, optional):
Adjacency of the target graph as a dict of form {t: Nt, ...}, where
t is a variable in the target graph and Nt is its set of neighbours.
This should be omitted if and only if embedding is an
EmbeddedStructure object.
chain_strength (float/mapping/callable, optional):
Sets the coupling strength between qubits representing variables
that form a :term:`chain`. Mappings should specify the required chain
strength for each variable. Callables should accept the BQM and
embedding and return a float or mapping. By default,
`chain_strength` is calculated with
:func:`~dwave.embedding.chain_strength.uniform_torque_compensation`.
smear_vartype (:class:`.Vartype`, optional, default=None):
Determines whether the linear bias of embedded variables is smeared
(the specified value is evenly divided as biases of a chain in the
target graph) in SPIN or BINARY space. Defaults to the
:class:`.Vartype` of `source_bqm`.
Returns:
:obj:`.BinaryQuadraticModel`: Target binary quadratic model.
Examples:
This example embeds a triangular binary quadratic model representing
a :math:`K_3` clique into a square target graph by mapping variable `c`
in the source to nodes `2` and `3` in the target.
>>> import networkx as nx
...
>>> target = nx.cycle_graph(4)
>>> # Binary quadratic model for a triangular source graph
>>> h = {'a': 0, 'b': 0, 'c': 0}
>>> J = {('a', 'b'): 1, ('b', 'c'): 1, ('a', 'c'): 1}
>>> bqm = dimod.BinaryQuadraticModel.from_ising(h, J)
>>> # Variable c is a chain
>>> embedding = {'a': {0}, 'b': {1}, 'c': {2, 3}}
>>> # Embed and show the chain strength
>>> target_bqm = dwave.embedding.embed_bqm(bqm, embedding, target)
>>> target_bqm.quadratic[(2, 3)]
-1.9996979771955565
>>> print(target_bqm.quadratic) # doctest: +SKIP
{(0, 1): 1.0, (0, 3): 1.0, (1, 2): 1.0, (2, 3): -1.9996979771955565}
See also:
:func:`.embed_ising`, :func:`.embed_qubo`
"""
if isinstance(embedding, EmbeddedStructure):
if target_adjacency is not None:
warnings.warn(
"target_adjacency should not be provided if embedding is an "
"EmbeddedStructure. The given value will be ignored. In the "
"future this will raise an exception",
DeprecationWarning,
stacklevel=2)
elif target_adjacency is None:
raise ValueError("either embedding should be an EmbeddedStructure, or "
"target_adjacency must be provided")
else:
target_edges = adjacency_to_edges(target_adjacency)
embedding = EmbeddedStructure(target_edges, embedding)
return embedding.embed_bqm(source_bqm,
smear_vartype=smear_vartype,
chain_strength=chain_strength)
def embed_bqm(source_bqm, embedding=None, target_adjacency=None,
chain_strength=1.0, smear_vartype=None):
"""Embed a binary quadratic model onto a target graph.
Args:
source_bqm (:obj:`.BinaryQuadraticModel`):
Binary quadratic model to embed.
embedding (dict/:class:`.EmbeddedStructure`):
Mapping from source graph to target graph as a dict of form
{s: {t, ...}, ...}, where s is a source-model variable and t is a
target-model variable. Alternately, an EmbeddedStructure object
produced by, for example,
EmbeddedStructure(target_adjacency.edges(), embedding). If embedding
is a dict, target_adjacency must be provided.
target_adjacency (dict/:obj:`networkx.Graph`, optional):
Adjacency of the target graph as a dict of form {t: Nt, ...}, where
t is a variable in the target graph and Nt is its set of neighbours.
This should be omitted if and only if embedding is an
EmbeddedStructure object.
chain_strength (float/mapping/callable, optional):
Magnitude of the quadratic bias (in SPIN-space) applied between
variables to form a chain, with the energy penalty of chain breaks
set to 2 * `chain_strength`. If a mapping is passed, a
chain-specific strength is applied. If a callable is passed, it
will be called on `chain_strength(source_bqm, embedding)` and should
return a float or mapping, to be interpreted as above.
smear_vartype (:class:`.Vartype`, optional, default=None):
Determines whether the linear bias of embedded variables is smeared
(the specified value is evenly divided as biases of a chain in the
target graph) in SPIN or BINARY space. Defaults to the
:class:`.Vartype` of `source_bqm`.
Returns:
:obj:`.BinaryQuadraticModel`: Target binary quadratic model.
Examples:
This example embeds a triangular binary quadratic model representing
a :math:`K_3` clique into a square target graph by mapping variable `c`
in the source to nodes `2` and `3` in the target.
>>> import networkx as nx
...
>>> target = nx.cycle_graph(4)
>>> # Binary quadratic model for a triangular source graph
>>> h = {'a': 0, 'b': 0, 'c': 0}
>>> J = {('a', 'b'): 1, ('b', 'c'): 1, ('a', 'c'): 1}
>>> bqm = dimod.BinaryQuadraticModel.from_ising(h, J)
>>> # Variable c is a chain
>>> embedding = {'a': {0}, 'b': {1}, 'c': {2, 3}}
>>> # Embed and show the chain strength
>>> target_bqm = dwave.embedding.embed_bqm(bqm, embedding, target)
>>> target_bqm.quadratic[(2, 3)]
-1.0
>>> print(target_bqm.quadratic) # doctest: +SKIP
{(0, 1): 1.0, (0, 3): 1.0, (1, 2): 1.0, (2, 3): -1.0}
See also:
:func:`.embed_ising`, :func:`.embed_qubo`
"""
if isinstance(embedding, EmbeddedStructure):
if target_adjacency is not None:
raise ValueError("target_adjacency should not be provided if "
"embedding is an EmbeddedStructure")
elif target_adjacency is None:
raise ValueError("either embedding should be an EmbeddedStructure, or "
"target_adjacency must be provided")
else:
target_edges = adjacency_to_edges(target_adjacency)
embedding = EmbeddedStructure(target_edges, embedding)
return embedding.embed_bqm(source_bqm, smear_vartype=smear_vartype,
chain_strength=chain_strength)