Qmasm

* The [Leap hybrid solver service](https://support.dwavesys.com/hc/en-us/articles/360043633273-Hybrid-Solver-Service) (HSS) is now supported.
* QMASM can now query the set of supported parameters on certain solvers, which should lead to slightly faster startup times.

QMASM is my first [PyPI](https://pypi.org/) 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](https://www.dwavesys.com/)'s proprietary and now-deprecated SAPI library to their open-source [Ocean](https://ocean.dwavesys.com/) 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](https://github.com/lanl/qmasm/wiki) 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/`](//github.com/lanl/qmasm/tree/v3.0/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`](//github.com/lanl/qmasm/tree/v3.0/examples/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](//github.com/lanl/qmasm/compare/v2.0...v3.0) 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`](https://github.com/dwavesystems/qbsolv) solver or the [MiniZinc](http://www.minizinc.org/) constraint-modeling language (using the [Chuffed](https://github.com/chuffed/chuffed) lazy clause generation solver as its back end).

See the [commit log](https://github.com/lanl/qmasm/compare/v1.2...v2.0) 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`](https://github.com/lanl/qmasm/wiki/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`](https://github.com/lanl/qmasm/wiki/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`](https://github.com/lanl/qmasm/wiki/qmasm-qbsolv), wraps D-Wave's [`qbsolv`](https://github.com/dwavesystems/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`](https://github.com/dwavesystems/qbsolv) and [MiniZinc](http://www.minizinc.org/) 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](https://github.com/lanl-ansi/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](http://www.minizinc.org/). (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.