dimod: Binary Quadratic Model API

Common errors

• TypeError: Parameters to generic types must be types. Got NotImplemented.

  cause This error often occurs when using older Python versions (e.g., Python 3.7.10) with newer dimod versions due to changes in Python's `typing` module or dependencies like NumPy.
  fix Ensure you are using a Python version supported by dimod (currently >=3.9) and compatible versions of its dependencies, especially NumPy. Upgrade Python to 3.9+.

• SolverFailureError: quadratic must be a sequence of length X

  cause This error typically indicates an issue with the structure or size of the binary quadratic model (BQM) being submitted to a solver, or a problem within the solver itself, possibly related to embedding or input validation.
  fix Carefully inspect the `quadratic` biases of your BQM. Ensure the quadratic interactions are correctly formed and that the BQM structure matches the expected input of the sampler. This can sometimes occur intermittently due to complex embedding challenges; try simplifying the problem or using a different embedding approach if applicable.

• AttributeError: module 'dimod' has no attribute 'meta'

  cause Attempting to access the `dimod.meta` namespace after it has been removed from the library.
  fix The functionality previously in `dimod.meta` has been migrated. Refer to the `dimod.core.sampler` namespace for equivalent functionality or update your code to reflect the current API design.

Warnings

• breaking Support for Python 3.8 was dropped in dimod version 0.12.18. Python 3.7.x support was dropped in earlier 0.10.x versions.
  Fix: Upgrade to Python 3.9 or higher. The current version 0.12.21 supports Python 3.9 through 3.14.
• deprecated The `dimod.meta` namespace and its contents (`SamplerABCMeta`, `samplemixinmethod`) were removed in dimod 0.10.5.
  Fix: Migrate to `dimod.core.sampler` namespace for related functionality.
• gotcha The `Variables._relabel()` method in versions prior to 0.12.21 could apply incorrect relabeling when given a superset of labels that corresponded to valid indices.
  Fix: Upgrade to dimod 0.12.21 or later to ensure correct relabeling behavior for variables.
• gotcha Inheritance in `ComposedSampler` and `ComposedPolySampler` was fixed in 0.12.20 to ensure composite attributes correctly override sampler attributes. Older versions might exhibit unexpected behavior if relying on this override.
  Fix: Upgrade to dimod 0.12.20 or later to ensure proper attribute resolution in composed samplers.

Install

• pip install dimod Install latest version

Imports

• BinaryQuadraticModel

  from dimod import BinaryQuadraticModel

• ExactSolver

  from dimod import ExactSolver

  ExactSolver is a reference solver for testing and small problems, not for production quantum hardware.
• SPIN
  wrong:

  from dimod.vartype import SPIN

  correct:

  from dimod import SPIN

  Vartype enumerations (SPIN, BINARY) are directly available under the `dimod` namespace.

Quickstart

This quickstart demonstrates how to create a BinaryQuadraticModel (BQM) with binary variables, solve it using dimod's built-in ExactSolver, and inspect the resulting samples and their energies. It also shows how to convert the BQM's variable type (vartype) between BINARY and SPIN.

import dimod

# Construct a simple QUBO problem
# Represents E(x0, x1) = -x0 - x1 + 2*x0*x1
bqm = dimod.BinaryQuadraticModel({0: -1, 1: -1}, {(0, 1): 2}, 0.0, dimod.BINARY)

# Use dimod's brute-force exact solver
sampler = dimod.ExactSolver()
response = sampler.sample(bqm)

print("SampleSet:\n", response)

# Access samples and energies
for sample, energy in response.data(['sample', 'energy']):
    print(f"Sample: {sample}, Energy: {energy}")

# Convert the BQM to Ising format
bqm_ising = bqm.change_vartype(dimod.SPIN, inplace=False)
print("\nIsing BQM vartype:", bqm_ising.vartype)