Quantum macro assembler for D-Wave systems
QMASM v4.1 introduces only two, relatively small, changes:
QMASM is my first PyPI package, and I didn't get all the metadata right on my first try. There are no code changes relative to v4.0. If I got everything right this time, you should be able to do a pip install qmasm to install QMASM.
After many months of effort, I finally finished rewriting QMASM from D-Wave's proprietary and now-deprecated SAPI library to their open-source Ocean API! The QMASM language has not changed, but some of the compiler options have, and the execution output is formatted slightly differently. See the QMASM documentation for usage details.
Two helper tools have been removed: qmasm-ground-state and qmasm-qbsolv. The former has been replaced by qmasm's --solver=exact option, and the latter has been replaced by its --qbsolv option (plus Ocean's various software solvers).
QMASM has undergone a substantial number of improvements—to both the language and the implementation—since the v2.0 release (22-Jun-2017). The following are some of the highlights:
QMASM automatically splits large sample counts (--samples==〈number〉) into as many QMI submissions as are required by the target D-Wave system and merges the results as if they were part of a single submission.
QMASM performs more aggressive qubit-count reduction at -O1 and above.
A simple Emacs major mode for editing QMASM code is provided in the extras/ directory.
A new !assert directive aids in filtering output and in debugging QMASM programs by specifying conditions on resulting values that are checked in a post-processing step.
In addition to supporting program-level chains (e.g., A = B), the QMASM language now supports program-level anti-chains (e.g., A /= B).
The command-line option --pin-strength has been renamed to --pin-weight.
The command-line options --discard and --all-solns have been replaced by a more intuitive --show option:
--show=valid (the default) outputs only valid solutions.
--show=best outputs the best solutions, even if they're invalid.
--show=all outputs all solutions, valid or invalid.
!use_macro can be used without an instance name. In this case, the macro is expanded without prepending an instance-name prefix to all of the symbols used in the macro.
!alias is now deprecated. Instead !let can be used to bind a symbol to another symbol (like !alias) or to bind a symbol to the result of an arithmetic expression, evaluated at compile time.
Conditional code evaluation is now possible with an !if…!else…!end_if construct, with the expected semantics.
Iteration of code blocks is now supported with a !for…!end_for construct, which can loop over either a fixed set of symbols or arithmetic/geometric integer sequences.
A new feature-test.qmasm file presents usage examples of all QMASM language features.
In addition, QMASM v3.0 includes numerous bug fixes. See the commit log for the complete list of changes.
All users should consider upgrading to QMASM v3.0.
It's been way too long since the last release of QMASM. Perhaps the most far-reaching improvement is that QMASM can now run programs even without access to D-Wave's hardware and proprietary software. In their place, QMASM can use either D-Wave's open-source qbsolv solver or the MiniZinc constraint-modeling language (using the Chuffed lazy clause generation solver as its back end).
See the commit log for the complete list of changes, but here are the highlights:
Pinning is implemented in terms of a chain to a biased qubit.
"Flattened" QMASM code can be output using --format=qmasm.
Spin-reversal transformations can be introduced to compensate for asymmetry in the hardware. Specify --spin-revs=number to indicate the number of random spin-reversals to perform.
Classical postprocessing can be applied to the D-Wave's output to search for better solutions that lie near the solutions found by the hardware. Specify --postproc=opt to enable "optimization" postprocessing, which is usually what you want.
A new script, qb2qmasm converts D-Wave programs from the format used on D-Wave's "Qubist" Web interface to QMASM code.
A new script, qmasm-ground-state, computes the complete ground state of a QMASM macro via exhaustive evaluation. This can be useful for verifying that a macro is defined correctly.
A new script, qmasm-qbsolv, wraps D-Wave's qbsolv solver. It uses comments introduced by --format=qbsolv to report results in terms of individual QMASM variables instead of as a single bit string.
!begin_replace_sym and !end_replace_sym directives perform regular-expression search-and-replace operations on symbol names after macro expansion.
The !use_macro directive can instantiate a macro multiple times in a single invocation. The !next. directive expands to the next instantiation name in a list of instantiations. These directives are useful for establishing a chain of macro instantiations, each feeding into the next.
QMASM honors a QMASMCACHE environment variable that points to a directory in which QMASM can cache problem embeddings. On subsequent executions of the same problem (or even a different problem with identical structure), QMASM can skip the (slow) embedding step and run programs much faster.
Instead of always discarding known-incorrect answers, --discard=no tells QMASM to retain them. --discard=maybe normally discards known-incorrect answers, but if no answers are left, it will retain the least incorrect of the remainder.
The --run option no longer requires hardware access. QMASM can additionally run programs with --format=qbsolv or --format=minizinc.
QMASM works with Python 3.x in addition to Python 2.x.
Custom topologies can be specified with --topology-file=filename as a means for gauging qubit counts at problems scales larger than what is supported by current hardware.
qbsolv and MiniZinc output can be generated either before (default) or after (with --always-embed) embedding into a topology.
Finer-grained control is provided over QMASM optimizations. -O (and -O1) merely attempt to reduce the logical qubit count, which is a fairly fast operation. -O2 additionally packs the problem as tightly as possible in a corner of the Chimera graph, which can take quite a long time.
Programs can be output in bqpjson format.
It is no longer forbidden to alias an undefined variable. Variables come into existence with weight 0.0 in that case.
In addition, there have been plenty of bug fixes. Most importantly, the implementation of the -O optimizations have been rewritten from scratch to address some serious correctness issues.
All users should consider upgrading from QMASM v1.2 to QMASM v2.0.
Version 1.2 of QMASM adds a new output format: the MiniZinc constraint-modeling language. (Use --format=minizinc on the qmasm command line.) This provides a way to run QMASM programs classically and more deterministically, which can be useful for debugging. In addition, QMASM v1.2 extends array syntax to aliases; introduces an --all-solns command-line option to include all solutions in the output, not just minimal-energy solutions; writes qbsolv files before embedding, not after (which largely defeated the purpose of outputting qbsolv); and includes various minor code improvements.
The biggest change since the previous release is support for array notation. It's now possible to write
this[0:2] = that[5:3]
instead of
this[0] = that[5]
this[1] = that[4]
this[2] = that[3]
and
thirteen[3:0] := 1101
instead of
thirteen[3] := 1
thirteen[2] := 1
thirteen[1] := 0
thirteen[0] := 1
Actually, an arguably even bigger change is that QASM has now been renamed to QMASM, which is a more unique name and manages to include the "M" in "quantum macro assembler".
The code has been made more robust to miscellaneous sources of confusion: lots of missing qubits/couplers in the topology, disconnected variables in the .qmasm source file, and both proxied and non-proxied network access.
All users should consider upgrading from QASM v1.0 to QMASM v1.1.
This is the first formal release of QASM. It was tested using Python 2.7.12, SAPI 2.4, and qOp 2.2, all on Ubuntu Linux 16.04 LTS (Xenial Xerus).