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 (strong coupler) betwen two symbols.

• 〈symbol1〉 〈-〉 〈symbol2〉

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

• 〈symbol〉 := 〈value〉

  Force a symbol to have a given Boolean value.

Directives

• !alias 〈symbol〉 〈token〉

  Replace a symbol with a given textual token in subsequent appearances.

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

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

• !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.

• !use_macro 〈macro-name〉 〈instance-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 ABC.XYZ 123 followed by DEF.XYZ 123.

• !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.

Other information

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).

QMASM is quite flexible with regard to symbol names: essentially all non-white-space characters are allowed. However, a few symbols should be used with care:

• # introduces comments and should be avoided in symbol names.

• ! 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.

• $ 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 problem inputs and outputs from the symbols needed to map inputs to outputs.

• " and ' are treated as in most Unix shells and can be used to introduce special characters such as spaces and hash marks in symbol names.

• \ escapes the next character, as in most Unix shells. This can also be used to introduce special characters such as spaces and hash marks in symbol names.

• [ 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.