Ising, QUBO, and BQMs¶
The binary quadratic model (BQM) class contains Ising and quadratic unconstrained binary optimization (QUBO) models used by samplers such as the DWave system.
The Ising model is an objective function of \(N\) variables \(s=[s_1,...,s_N]\) corresponding to physical Ising spins, where \(h_i\) are the biases and \(J_{i,j}\) the couplings (interactions) between spins.
The QUBO model is an objective function of \(N\) binary variables represented as an upperdiagonal matrix \(Q\), where diagonal terms are the linear coefficients and the nonzero offdiagonal terms the quadratic coefficients.
The BinaryQuadraticModel
class can contain both these models and its methods provide
convenient utilities for working with, and interworking between, the two representations
of a problem.
These models and their use in solving problems on the DWave system is described in the following documentation:
 Getting Started with the DWave System
 Introduces key concepts such as objective functions, Ising model, QUBOs, and graphs, explains how these models are used to represent problems, and provides some simple examples.
 DWave ProblemSolving Handbook
 Provides a variety of techniques for, and examples of, reformulating problems as BQMs.
 Solving Problems on a DWave System
 Describes and demonstrates the use of BQM in the context of Ocean software.
Class¶

class
BinaryQuadraticModel
(*args, **kwargs)[source]¶ Encodes a binary quadratic model.
Binary quadratic model is the superclass that contains the Ising model and the QUBO.
Parameters:  linear (dict[variable, bias]) – Linear biases as a dict, where keys are the variables of the binary quadratic model and values the linear biases associated with these variables. A variable can be any python object that is valid as a dictionary key. Biases are generally numbers but this is not explicitly checked.
 quadratic (dict[(variable, variable), bias]) – Quadratic biases as a dict, where keys are 2tuples of variables and values the quadratic biases associated with the pair of variables (the interaction). A variable can be any python object that is valid as a dictionary key. Biases are generally numbers but this is not explicitly checked. Interactions that are not unique are added.
 offset (number) – Constant energy offset associated with the binary quadratic model.
Any input type is allowed, but many applications assume that offset is a number.
See
BinaryQuadraticModel.energy()
.  vartype (
Vartype
/str/set) –Variable type for the binary quadratic model. Accepted input values:
Vartype.SPIN
,'SPIN'
,{1, 1}
Vartype.BINARY
,'BINARY'
,{0, 1}
 **kwargs – Any additional keyword parameters and their values are stored in
BinaryQuadraticModel.info
.
Notes
The
BinaryQuadraticModel
class does not enforce types on biases and offsets, but most applications that use this class assume that they are numeric.Examples
This example creates a binary quadratic model with three spin variables.
>>> bqm = dimod.BinaryQuadraticModel({0: 1, 1: 1, 2: .5}, ... {(0, 1): .5, (1, 2): 1.5}, ... 1.4, ... dimod.Vartype.SPIN)
This example creates a binary quadratic model with nonnumeric variables (variables can be any hashable object).
>>> bqm = dimod.BQM({'a': 0.0, 'b': 1.0, 'c': 0.5}, ... {('a', 'b'): 1.0, ('b', 'c'): 1.5}, ... 1.4, ... dimod.SPIN) >>> len(bqm) 3 >>> 'b' in bqm True

linear
¶ Linear biases as a dict, where keys are the variables of the binary quadratic model and values the linear biases associated with these variables.
Type: dict[variable, bias]

quadratic
¶ Quadratic biases as a dict, where keys are 2tuples of variables, which represent an interaction between the two variables, and values are the quadratic biases associated with the interactions.
Type: dict[(variable, variable), bias]

offset
¶ The energy offset associated with the model. Same type as given on instantiation.
Type: number

variables
¶ The variables in the binary quadratic model as a dictionary keys view object.
Type: keysview

adj
¶ The model’s interactions as nested dicts. In graphic representation, where variables are nodes and interactions are edges or adjacencies, keys of the outer dict (adj) are all the model’s nodes (e.g. v) and values are the inner dicts. For the inner dict associated with outerkey/node ‘v’, keys are all the nodes adjacent to v (e.g. u) and values are quadratic biases associated with the pair of inner and outer keys (u, v).
Type: dict
Examples
This example creates an instance of the
BinaryQuadraticModel
class for the K4 complete graph, where the nodes have biases set equal to their sequential labels and interactions are the concatenations of the node pairs (e.g., 23 for u,v = 2,3).>>> import dimod ... >>> linear = {1: 1, 2: 2, 3: 3, 4: 4} >>> quadratic = {(1, 2): 12, (1, 3): 13, (1, 4): 14, ... (2, 3): 23, (2, 4): 24, ... (3, 4): 34} >>> offset = 0.0 >>> vartype = dimod.BINARY >>> bqm_k4 = dimod.BinaryQuadraticModel(linear, quadratic, offset, vartype) >>> bqm_k4.info = {'Complete K4 binary quadratic model.'} >>> bqm_k4.info.issubset({'Complete K3 binary quadratic model.', ... 'Complete K4 binary quadratic model.', ... 'Complete K5 binary quadratic model.'}) True >>> bqm_k4.adj.viewitems() # Show all adjacencies # doctest: +SKIP [(1, {2: 12, 3: 13, 4: 14}), (2, {1: 12, 3: 23, 4: 24}), (3, {1: 13, 2: 23, 4: 34}), (4, {1: 14, 2: 24, 3: 34})] >>> bqm_k4.adj[2] # Show adjacencies for node 2 # doctest: +SKIP {1: 12, 3: 23, 4: 24} >>> bqm_k4.adj[2][3] # Show the quadratic bias for nodes 2,3 # doctest: +SKIP 23
Vartype Properties¶
QUBO (binaryvalued variables) and Ising (spinvalued variables) instances of a BQM.
BinaryQuadraticModel.binary 

BinaryQuadraticModel.spin 
Methods¶
Construction Shortcuts¶
BinaryQuadraticModel.empty (vartype) 
Create a new empty binary quadratic model. 
Adding and Removing Variables and Interactions¶
BinaryQuadraticModel.add_variable ([v, bias]) 
Add a variable to the binary quadratic model. 
BinaryQuadraticModel.add_variables_from (linear) 
Add variables and/or linear biases to a binary quadratic model. 
BinaryQuadraticModel.add_interaction (u, v, bias) 
Add an interaction and/or quadratic bias to a binary quadratic model. 
BinaryQuadraticModel.add_interactions_from (…) 
Add interactions and/or quadratic biases to a binary quadratic model. 
BinaryQuadraticModel.add_offset (offset) 
Add specified value to the offset of a binary quadratic model. 
BinaryQuadraticModel.remove_variable ([v]) 
Remove a variable and its associated interactions. 
BinaryQuadraticModel.remove_variables_from (…) 
Remove the given variables from the binary quadratic model. 
BinaryQuadraticModel.remove_interaction (u, v) 
Remove the interaction between variables u and v. 
BinaryQuadraticModel.remove_interactions_from (…) 
Remove the given interactions from the binary quadratic model. 
BinaryQuadraticModel.remove_offset () 
Set the binary quadratic model’s offset to zero. 
BinaryQuadraticModel.update (other) 
Update the binary quadratic model, adding biases from another. 
Transformations¶
BinaryQuadraticModel.contract_variables (u, v) 
Enforce u, v being the same variable in a binary quadratic model. 
BinaryQuadraticModel.fix_variable (v, value) 
Remove a variable by fixing its value. 
BinaryQuadraticModel.fix_variables (fixed) 
Fix the value of the variables and remove them. 
BinaryQuadraticModel.flip_variable (v) 
Flip variable v in a binary quadratic model. 
BinaryQuadraticModel.normalize ([bias_range, …]) 
Normalizes the biases of the binary quadratic model such that they fall in the provided range(s), and adjusts the offset appropriately. 
BinaryQuadraticModel.relabel_variables (mapping) 
Relabel variables of a binary quadratic model as specified by mapping. 
BinaryQuadraticModel.scale (scalar[, …]) 
Multiply all the biases by the specified scalar. 
Change Vartype¶
BinaryQuadraticModel.change_vartype (vartype) 
Return a binary quadratic model with the specified vartype. 
Copy¶
BinaryQuadraticModel.copy () 
Create a copy of a binary quadratic model. 
Energy¶
BinaryQuadraticModel.energy (sample[, dtype]) 

BinaryQuadraticModel.energies (samples_like) 
Determine the energies of the given samples. 
Converting To and From Other Formats¶
BinaryQuadraticModel.from_coo (obj[, vartype]) 
Deserialize a binary quadratic model from a COOrdinate format encoding. 
BinaryQuadraticModel.from_ising (h, J[, offset]) 
Create a binary quadratic model from an Ising problem. 
BinaryQuadraticModel.from_networkx_graph (G) 
Create a binary quadratic model from a NetworkX graph. 
BinaryQuadraticModel.from_numpy_matrix (mat) 
Create a binary quadratic model from a NumPy array. 
BinaryQuadraticModel.from_numpy_vectors (…) 
Create a binary quadratic model from vectors. 
BinaryQuadraticModel.from_qubo (Q[, offset]) 
Create a binary quadratic model from a QUBO problem. 
BinaryQuadraticModel.from_pandas_dataframe 

BinaryQuadraticModel.from_serializable (obj) 
Deserialize a binary quadratic model. 
BinaryQuadraticModel.to_coo ([fp, vartype_header]) 
Serialize the binary quadratic model to a COOrdinate format encoding. 
BinaryQuadraticModel.to_ising () 
Converts a binary quadratic model to Ising format. 
BinaryQuadraticModel.to_networkx_graph ([…]) 
Convert a binary quadratic model to NetworkX graph format. 
BinaryQuadraticModel.to_numpy_matrix ([…]) 
Convert a binary quadratic model to NumPy 2D array. 
BinaryQuadraticModel.to_numpy_vectors ([…]) 
The BQM as 4 numpy vectors, the offset and a list of variables. 
BinaryQuadraticModel.to_qubo () 
Convert a binary quadratic model to QUBO format. 
BinaryQuadraticModel.to_pandas_dataframe 

BinaryQuadraticModel.to_serializable ([…]) 
Convert the binary quadratic model to a serializable object. 
Alias¶

BQM
¶ Alias for
BinaryQuadraticModel
alias of
dimod.binary_quadratic_model.BinaryQuadraticModel