Skip to content

Quick start

Jump to bottom
Scott Pakin edited this page Jun 3, 2020 · 8 revisions

A quick introduction to QMASM

QMASM is implemented using D-Wave Ocean so you will first need to install and configure that. If you don't have access to a a D-Wave system—and note that you can get free but limited access via a Leap account—you can add --solver=neal to your qmasm command lines below to use a software simulated annealer instead of one of D-Wave's hardware quantum annealers.

As a test of QMASM, consider a program that favors exactly one "on" bit out of five. This might be used as a building block for a larger program (e.g., a partitioning problem in which each bin contains exactly one out of five available objects). The truth table of acceptable solutions looks like this:

A B C D E
F F F F T
F F F T F
F F T F F
F T F F F
T F F F F

The challenge is in representing that table in terms of weights and strengths. That's a subject for a separate discussion. For now, we show only how to describe the result of that computation in QMASM format:

#################################################
# QMASM example: one "on" bit out of five total #
# By Scott Pakin <[email protected]>               #
#################################################

# Point weights
# A-E are the variables we care about.
# $a1-$a3 are ancillary variables.
A   -2
B    1
C   -2
D   -1
E    1
$a1  0
$a2  4
$a3  3

# Coupler strengths
A   B    2
A   C    2
A   D    2
A   E    1
A   $a1  1
A   $a2 -4
A   $a3 -4
B   C    2
B   D    2
B   E    1
B   $a1  1
B   $a2 -4
B   $a3 -1
C   D    2
C   E    3
C   $a1 -1
C   $a2 -4
C   $a3 -4
D   E    4
D   $a1 -2
D   $a2 -4
D   $a3 -3
E   $a1 -4
E   $a2  0
E   $a3 -4
$a1 $a2 -4
$a1 $a3  3
$a2 $a3  0

(Download as 1of5.qmasm.)

Note that in addition to the truth-table variables A-E we employ three helper variables, $a1, $a2, and $a3. In fact, a one-of-five problem can be encoded without any helper variables. They are included here to show how qmasm does not normally output values for variables with a $ in their name because they are deemed "internal" or "uninteresting" variables.

Simply passing 1of5.qmasm to qmasm outputs a physical layout suitable for entry into D-Wave's Qubist interface:

$ qmasm 1of5.qmasm

By default, output goes to the standard output device. In addition, QMASM produces a mapping from variables to physical qubit numbes on the standard error device, for example

# A --> 11 15 43
# B --> 39 47
# C --> 9 41
# D --> 8 12 40
# E --> 10 14 42

The exact mapping you see will almost certainly differ from the above.

To actually run the program right from qmasm and report the results, simply add --run to the command line:

$ qmasm --run 1of5.qmasm
# A -->  144  272
# B -->  278  281  286
# C -->  277  283  285
# D -->  147  151  275
# E -->  276  282  284
Solution #1 (energy = -25.0000, tally = 85):

    Variable  Value
    --------  -----
    A         False
    B         False
    C         False
    D         False
    E         True

Solution #2 (energy = -25.0000, tally = 156):

    Variable  Value
    --------  -----
    A         False
    B         False
    C         False
    D         True
    E         False

Solution #3 (energy = -25.0000, tally = 162):

    Variable  Value
    --------  -----
    A         False
    B         False
    C         True
    D         False
    E         False

Solution #4 (energy = -25.0000, tally = 251):

    Variable  Value
    --------  -----
    A         False
    B         True
    C         False
    D         False
    E         False

Solution #5 (energy = -25.0000, tally = 153):

    Variable  Value
    --------  -----
    A         True
    B         False
    C         False
    D         False
    E         False

Again, the output you receive will differ from the above, but you should see five solutions, each with a single True variable and four False variables.

In the preceding output, lines starting with "#" are written to the standard error device, and the rest of the lines are written to the standard output device. Additional information about the execution—solver properties, mapping properties, timing data, solution characteristics, and more—can be written to the standard error device by providing the -v (verbose) option to qmasm:

Specifying -v twice writes even more information about the execution to the standard error device. This extended information additionally includes qmasm's internal, canonicalized representation of the input file; the complete set of solver properties, including a list of all available qubits and couplers; and a solution-energy histogram. Within each solution, all variables are output, not just "interesting" variables (those without a "$" in their name). Consequently, -v -v (or -vv for short) can be a handy debugging aid.

Clone this wiki locally