Skip to content
Go to file

Latest commit

* add coupler set filter feature
* add spin set filter feature
* add tests for coupler and spin filters

Git stats


Failed to load latest commit information.
Latest commit message
Commit time

D-Wave Instance Generator (D-WIG)

Build Status codecov

The D-WIG toolset is used to generate binary quadratic programs based on a specific D-Wave QPU. A key motivation for generating problems on a specific QPU is that these problems do not require an embedding step to test them on the hardware. The D-WIG problem generator assumes that the QPU has a chimera topology. is the primary entry point and generates binary unconstrained quadratic programming problems (B-QP) in the bqpjson format.

The remainder of this documentation assumes that,

  1. You have access to a D-Wave QPU and the SAPI binaries
  2. You are familiar with the D-Wave Qubist interface
  3. You are using a bash terminal


The D-WIG toolset requires dwave-cloud-client, dwave_networkx and bqpjson to run and pytest for testing. These requirements can be installed with,

pip install -r requirements.txt

The installation can be tested by running,



Basic Usage

The primary entry point of the D-WIG toolset is this script is used to generate a variety of B-QP problems, which have been studied in the literature. For example, the following command will generate a RAN1 problem for a full yield QPU of chimera degree 12 and send it to standard output,

./ ran

Bash stream redirection can be used to save the standard output to a file, for example,

./ ran > ran1.json

The ran1.json file is a json document in the bqpjson format. A detailed description of this format can be found in the bqpjson python package.

A helpful feature of D-WIG is to reduce the size of the QPU that you are working with. The chimera degree argument -cd n can be used to reduce D-WIG's view of the full QPU to a smaller n-by-n QPU. For example try,

./ -cd 2 ran

A detailed list of all command line options can be viewed via,

./ --help

Problem Types

The D-Wig toolset currently supports three types of problem generation,

  1. const - fields are couplers are set to a given constant value
  2. ran - fields are couplers are set uniformly at random
  3. fl - frustrated loops
  4. wscn - weak-strong cluster networks
  5. fclg - frustrated cluster loops and gadgets

A detailed list of command line options for each problem type can be viewed via,

./ <problem type> --help

See the doc strings inside of for additional documentation on each of these problem types.

Connecting to a QPU

D-WIG uses the dwave-cloud-client for connecting to the QPU and will use your dwave.conf file for the configuration details. A specific profile can be selected with the command line argument --profile <label>. If no configuration details are found, D-WIG will assume a full yield QPU of chimera degree 16. The command line argument --ignore-connection can be used to ignore the defaults specified in dwave.conf.

Viewing a B-QP

The Qubist Solver Visualization tool is helpful in understanding complex B-QP datasets. To that end, the script converts a B-QP problem into the Qubist Hamiltonian format so that it can be viewed in the Solver Visualization tool. For example, the following command will generate a 2-by-2 RAN1 problem in the qubist format and then print it to standard output,

./ -cd 2 ran | bqp2qh

To view this problem paste the terminal output into the Data tab of the Qubist Solver Visualization tool.

Spin vs Boolean Variables

The B-QP format supports problems with spin variables (i.e. {-1,1}) and boolean variables (i.e. {0,1}). However, the D-WIG toolset generates problems only using spin variables. The tool can be used to make the transformation after the problem is generated. For example, the following command will generate 2-by-2 RAN1 problem and convert it to a boolean variable space,

./ -cd 1 ran | spin2bool -pp

The QUBO Format

The QUBO format is supported by a variety of the tools provided by D-Wave, such as qbsolv, aqc, and toq. The tool can be combined with the tool to convert D-WIG cases into the qubo format. For example, the following command will generate 2-by-2 RAN1 problem and convert it to the QUBO format,

./ -cd 1 ran | spin2bool | bqp2qubo


This code has been developed as part of the Advanced Network Science Initiative at Los Alamos National Laboratory. The primary developer is Carleton Coffrin.

The D-WIG development team would like to thank Denny Dahl for suggesting the D-WIG name. Special thanks are given to these works, which provided significant inspiration for the D-WIG toolset.

For the RAN-pr formulation,

  author = {Zdeborova, Lenka and Krzakala, Florent},
  title = {Statistical physics of inference: thresholds and algorithms},
  journal = {Advances in Physics},
  volume = {65},
  number = {5},
  pages = {453-552},
  year = {2016},
  doi = {10.1080/00018732.2016.1211393},
  URL = {}

For the RAN-k formulation,

  title={Benchmarking a quantum annealing processor with the time-to-target metric},
  author={King, James and Yarkoni, Sheir and Nevisi, Mayssam M and Hilton, Jeremy P and McGeoch, Catherine C},
  journal={arXiv preprint arXiv:1508.05087},

For the FL-k formulation,

  title={Performance of a quantum annealer on range-limited constraint satisfaction problems},
  author={King, Andrew D and Lanting, Trevor and Harris, Richard},
  journal={arXiv preprint arXiv:1502.02098},

For the FCL-k formulation,

  title={Quantum Annealing amid Local Ruggedness and Global Frustration},
  author={King, James and Yarkoni, Sheir and Raymond, Jack and Ozfidan, Isil and King, Andrew D and Nevisi, Mayssam Mohammadi and Hilton, Jeremy P, and McGeoch, Catherine C},
  journal={arXiv preprint arXiv:1701.04579},

For the weak-strong cluster network formulation,

  title={What is the Computational Value of Finite-Range Tunneling?},
  author={Denchev, Vasil S and Boixo, Sergio and Isakov, Sergei V and Ding, Nan and Babbush, Ryan and Smelyanskiy, Vadim and Martinis, John and Neven, Hartmut},
  journal={Physical Review X},

For the frustrated cluster loops and gadgets formulation,

  title = {Demonstration of a Scaling Advantage for a Quantum Annealer over Simulated Annealing},
  author = {Albash, Tameem and Lidar, Daniel A.},
  journal = {Phys. Rev. X},
  volume = {8},
  issue = {3},
  pages = {031016},
  numpages = {26},
  year = {2018},
  month = {Jul},
  publisher = {American Physical Society},
  doi = {10.1103/PhysRevX.8.031016},
  url = {}

For the corrupted biased ferromagnet,

  author="Pang, Yuchen and Coffrin, Carleton and Lokhov, Andrey Y. and Vuffray, Marc",
  title="The Potential of Quantum Annealing for Rapid Solution Structure Identification",
  booktitle="Integration of Constraint Programming, Artificial Intelligence, and Operations Research",
  editor="Hebrard, Emmanuel and Musliu, Nysret",
  publisher="Springer International Publishing"


D-WIG is provided under a BSD-ish license with a "modifications must be indicated" clause. See the file for the full text. This package is part of the Hybrid Quantum-Classical Computing suite, known internally as LA-CC-16-032.

You can’t perform that action at this time.