# Introduction¶

dimod provides a binary quadratic model (BQM) class that encodes Ising and quadratic unconstrained binary optimization (QUBO) models used by samplers such as the D-Wave system.

It provides useful functionality for working with these models and samplers; for example generators_dimod to build BQMs and Utilities for calculating the energy of a sample or serializing dimod objects.

It includes reference samplers and composites for processing binary quadratic programs and refining sampling, and useful for testing your code during development.

It also provides an API for Samplers and Composites for constructing new samplers and composed samplers tailored for your problem.

Additionally, it provides some Higher-Order Composites and functionality such as reducing higher-order polynomials to BQMs.

- For an introduction to BQMs, see Binary Quadratic Models.
- For an introduction to samplers and composites, see Samplers and Composites.

## Examples¶

Solving problems with large numbers of variables might necessitate the use of decomposition[1] methods such as branch-and-bound to reduce the number of variables. The following illustrative example reduces an Ising model for a small problem (the K4 complete graph), and converts the reduced-variables model to QUBO formulation.

[1] | Ocean software’s D-Wave Hybrid provides tools for decomposing large problems. |

```
>>> 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}
>>> bqm_k4 = dimod.BinaryQuadraticModel(linear, quadratic, 0.5, dimod.SPIN)
>>> bqm_k4.vartype
<Vartype.SPIN: frozenset([1, -1])>
>>> len(bqm_k4.linear)
4
>>> bqm_k4.contract_variables(2, 3)
>>> len(bqm_k4.linear)
3
>>> bqm_no3_qubo = bqm_k4.binary
>>> bqm_no3_qubo.vartype
<Vartype.BINARY: frozenset([0, 1])>
```

The next example uses a composed sampler on the Boolean NOT Gate
example detailed in the Getting Started documentation.
The `ExactSolver`

test sampler calculates the
energy of all possible samples; the `FixedVariableComposite`

composite sets the value and removes specified variables from the BQM before sending it to
the sampler. Fixing variable x, the input to the NOT gate, to 1 results in valid solution
\(z=0\) having lower energy (-1) than solution \(x=z=1\), which is an invalid
state for a NOT gate.

```
>>> from dimod import FixedVariableComposite, ExactSolver
>>> Q = {('x', 'x'): -1, ('x', 'z'): 2, ('z', 'x'): 0, ('z', 'z'): -1}
>>> composed_sampler = FixedVariableComposite(ExactSolver())
>>> sampleset = composed_sampler.sample_qubo(Q, fixed_variables={'x': 1})
>>> print(sampleset)
x z energy num_oc.
0 1 0 -1.0 1
1 1 1 0.0 1
['BINARY', 2 rows, 2 samples, 2 variables]
```

The next example creates a dimod sampler by implementing a single method (in this example
the `sample_ising()`

method).

```
class LinearIsingSampler(dimod.Sampler):
def sample_ising(self, h, J):
sample = linear_ising(h, J) # Defined elsewhere
energy = dimod.ising_energy(sample, h, J)
return dimod.Response.from_samples([sample], {'energy': [energy]})
@property
def properties(self):
return dict()
@property
def parameters(self):
return dict()
```

The `Sampler`

ABC provides the other sample methods “for free”
as mixins.