File format

An input file (typical extension: .qmasm) is parsed line-by-line. Each line must be in one of the forms listed below.

Statements

• 〈symbol〉 〈weight〉

  Assign a point weight to a given symbol.

• 〈symbol1〉 〈symbol2〉 〈strength〉

  Assign a coupler strength between two symbols.

• 〈symbol1〉 = 〈symbol2〉

  Create a chain (strongly negative coupler) between two symbols.

• 〈symbol1〉 /= 〈symbol2〉

  Create an anti-chain (strongly positive coupler) between two symbols.

• 〈symbol〉 := 〈value〉

  Force a symbol to have a given Boolean value.

• 〈symbol1〉 〈-〉 〈symbol2〉

  Indicate that two symbols are aliases of each other (i.e., two names for the same variable).

• 〈symbol1〉 -〉 〈symbol2〉

  Replace all previously appearing instances of 〈symbol1〉 with 〈symbol2〉.

Directives

• !bqm_type qubo | ising

  Indicate if weights and strengths are to be interpreted as QUBO or Ising parameters. The default is ising. In a QUBO problem, the variables being solved for are either 0 or 1. In an Ising problem, the variables being solved for are either −1 or +1. !bqm_type can be used repeatedly in a program, enabling parts of the program to be expressed as QUBOs and parts of it to be expressed as Ising-model Hamiltonians.

• !begin_macro 〈macro-name〉 … !end_macro 〈macro-name〉

  Assign a name to a block of statements so it can easily be reused.

• !use_macro 〈macro-name〉 [〈instance-name〉…]

  Instantiate a macro one or more times, prefixing each symbol the macro references with a given instance name followed by a period. For example, if macro mymacro includes the line XYZ 123, !use_macro mymacro ABC performs the equivalent of ABC.XYZ 123. Likewise, !use_macro mymacro ABC DEF performs the equivalent of both ABC.XYZ 123 and DEF.XYZ 123. If no instance names are supplied, the macro is instantiated with no additional prefix. That is, !use_macro mymacro performs the equivalent of XYZ 123.

• !include 〈filename〉

  Process a named auxiliary file as if its contents were pasted into the current file. If the filename appears within double quotes ("helper"), QMASM searches the current directory for the file. If the filename appears within angle brackets (〈helper〉), QMASM additionally searches all (colon-separated) directories named by the QMASMPATH environment variable. If no file extension is specified, .qmasm is assumed.

• !let 〈symbol〉 := 〈expression〉

  Evaluate an arithmetic expression and bind the result to the given symbol within the current scope.

• !let 〈symbol₁〉 := 〈symbol₂〉

  Bind 〈symbol₁〉 to 〈symbol₂〉 in the current scope. All subsequent instances of 〈symbol₁〉 in the current scope will be replaced with 〈symbol₂〉.

• !if 〈relation〉

  〈statements₁〉

  !else

  〈statements₂〉

  !end_if

  If 〈relation〉 evaluates to true, expand 〈statements₁〉. Otherwise, expand 〈statements₂〉. The !else 〈statements₂〉 clause can be omitted.

• !for 〈symbol〉 := 〈expression〉 [, 〈expression〉]… , ..., 〈expression〉

  〈statements〉

  !end_for

  Evaluate 〈statements〉 with 〈symbol〉 bound successively to each value in the given arithmetic or geometric sequence. See Loops below for sample usage.

• !for 〈symbol〉 := 〈symbol〉 [, 〈symbol〉]…

  〈statements〉

  !end_for

  Evaluate 〈statements〉 with 〈symbol〉 bound successively to each symbol that appears on the right-hand side of the :=. See Loops below for sample usage.

• !assert 〈relation〉

  Assert at post-processing time a property of a correct solution. Unless --show=all is specified (or when no better solution is available, --show=best), QMASM discards any solution that violates an assertion. See Assertions below for details.

• !next.

  When used within a symbol name, !next. instructs !use_macro to use the next instance name rather than the current instance name for that symbol. If there is no next instance name, the entire statement is discarded.

• !alias 〈symbol〉 〈token〉

  Deprecated. Replace a symbol with a given textual token in subsequent appearances. New code should instead use !let 〈symbol〉 := 〈token〉.

Order of operations

The following operators are listed in decreasing order of precedence:

Type	Operators	Associativity	Notes
Primary	( )	N/A	Grouping
Power	**	Right-to-left	Raise an integer to a non-negative power
Unary	+ - ~, !	Right-to-left	~ is integer bitwise negation; ! is logical negation (0 → 1, non-zero → 0)
Multiplicative	* / % & << >>	Left-to-right	% means remainder; & is bitwise AND; << and >> are left/right bit shifts
Additive	+ - | ^	Left-to-right	| is bitwise OR; ^ is bitwise XOR
Relational	< > <= >= = /=	N/A	/= means not equal to
Conjunctive	&&	N/A	True if both relations are true
Disjunctive	||	N/A	True if either relation is true

An additional primary construct, not listed in the preceding table, is if 〈relation〉 then 〈expression〉 else 〈expression〉 endif, with the expected interpretation. Note that the else clause cannot be omitted.

Arithmetic expressions are integer-valued. Consequently, only integer constants can be represented, and division (/) rounds down to the nearest integer.

Variables—the same symbols that appear in the program—always take on 0 for false and 1 for true, regardless of the --qubo setting.

QMASM coerces false to 0 and true to 1 when a relation is used as an arithmetic expression. Similarly, QMASM coerces 0 to false and non-0 to true when an arithmetic expression is used as a relation.

Loops

QMASM supports looping over integer sequences or over symbols. The following is an example of looping over the numbers from 1 to 10:

!for i := 1, ..., 10
  !let i1 := i + 1
  a[i] /= a[i1]
!end_for

The preceding code is equivalent to

a[1] /= a[2]
a[2] /= a[3]
a[3] /= a[4]
a[4] /= a[5]
a[5] /= a[6]
a[6] /= a[7]
a[7] /= a[8]
a[8] /= a[9]
a[9] /= a[10]
a[10] /= a[11]

Non-unit increments are supported. The loop

!for i := 1, 3, ..., 10
  !let i1 := i + 1
  a[i] /= a[i1]
!end_for

is shorthand for

a[1] /= a[2]
a[3] /= a[4]
a[5] /= a[6]
a[7] /= a[8]
a[9] /= a[10]

Geometric sequences are also supported. Hence,

!for i := 1, 2, 4, ..., 64
  !let i2 := i*2
  a[i] /= a[i2]
!end_for

is shorthand for

a[1] /= a[2]
a[2] /= a[4]
a[4] /= a[8]
a[8] /= a[16]
a[16] /= a[32]
a[32] /= a[64]
a[64] /= a[128]

In addition to arithmetic sequences, !for loops can iterate over an explicit set of symbol names. For example,

!for sym := bar, baz, qux, quux, corge, grault, garply, waldo, fred, plugh, xyzzy, thud
  sym -0.5
!end_for

expands to

bar -0.5
baz -0.5
qux -0.5
quux -0.5
corge -0.5
grault -0.5
garply -0.5
waldo -0.5
fred -0.5
plugh -0.5
xyzzy -0.5
thud -0.5

Assertions

An !assert directive's relation accepts any of the operators described in Order of operations above.

The following is an example of adding an assertion to the room macro from maze6x6.qmasm to specify that the minimal path must either enter and exit the room or not pass through the room at all:

!begin_macro room
!assert N+E+S+W = 0 || N+E+S+W = 2
N   0.50
E   0.50
S   0.50
W   0.50
$a1 1.00
   ⋮
!end_macro room

Other information

Symbol names are case-sensitive.

Blank lines are ignored.

Comments begin with # and continue to the end of the line.

White space separates fields. Hence, programs must specify A = B to assign a coupler strength, not A=B.

Weights and strengths are floating-point numbers and are expressed in "typical" floating-point syntax.

Booleans are expressed as 1, +1, T, or TRUE for "true" and 0, -1, F, or FALSE for "false" (case-insensitive).

New variable scopes are introduced by !begin_macro, !if, !else, and !for and end at the respective !end_macro, !else, !end_if, or !end_for.

QMASM is quite flexible with regard to symbol names. Essentially, only operator characters (see Order of operations above)—-, +, *, /, %, &, |, ^, ~, (, ), <, =, and >—the comment character (#), commas (,), and white space are forbidden. In addition, certain symbols are allowed but should be used with care:

• ! at the beginning of a line introduces a directive. Directives currently recognized by QMASM are listed above. While QMASM allows other symbols to begin with !, this practice is discouraged for future compatibility reasons.

• . is added automatically by !use_macro to construct new symbol names from an instantiation name plus a base symbol name. For example, if macro M, which defines symbol S, is instantiated as I, then the instantiated symbol is called I.S.

• $ anywhere in a symbol name indicates that the symbol should be considered "internal" or "uninteresting". QMASM outputs the values of such symbols only at higher levels of verbosity. Hence, $ is useful for distinguishing the symbols needed to map inputs to outputs from overall problem inputs and outputs.

• [ and ] are used to specify a list of symbols in =, /=, 〈-〉, ->, and := statements (including on the command line with --pin). The syntax "〈name〉[〈start〉:〈end〉]" (or, equivalently, "〈name〉[〈start〉..〈end〉]") with 〈start〉 and 〈end〉 both being nonnegative integers expands to one instance for each number from 〈start〉 to 〈end〉, both inclusive. For example, quux[1:3] expands to quux[1] quux[2] quux[3], and corge[10:8] expands to corge[10] corge[9] corge[8]. Only strides of ±1 are currently supported. Invalid ranges between the brackets simply don't expand.

:= supports assigning multiple values at once. For example, alice bob eve := true true false biases each of alice and bob to true and eve to false. No spaces are needed between right-hand side values consisting exclusively of 0 and 1 characters, as in thirteen[3:0] := 1101.

-> supports renaming multiple symbols at once. For example, laurel hardy -> abbott costello renames all prior occurrences of symbol laurel to abbott and all prior occurrences of symbol hardy to costello. It can even be used to swap symbols; annabel ellen -> ellen annabel simultaneously replaces all prior instances of annabel with ellen and ellen with annabel.