In the underlying Qrack library, inline methods have been reviewed and refactored, based upon our best guess as to what methods could be optimized when inline. In some cases, this results in a very slightly smaller binary. Most users will likely notice no difference in performance, but, on hypothetical very limited systems, CPU cache performance might benefit.

In line with the previous release, SSE2.0 and SSE3.0 are now optionally available in Qrack for float-precision complex norm operations. Further, calls to measure probability leverage this optional support by reading 2 complex number amplitudes at a time, before calculating their norm. (Binaries without SSE support did not require an update.) Credit for this incremental change to Qrack should go to https://stackoverflow.com/questions/6996764/fastest-way-to-do-horizontal-sse-vector-sum-or-other-reduction#answer-35270026.

This release makes minor improvements in CPU-based simulation. CPU-based state vector reads are now loaded two at a time into a complex2 object, giving a minor improvement to CPU-based gate simulation in general. Also. the default value of PSTRIDEPOW has been re-tuned, which will tend to increase speed, but we suggest looking at benchmarks (such as test_qft_cosmology in the C++ Qrack benchmark suite) for comparing PSTRIDEPOW value performance and tuning this setting on a per-system basis, in general.

Most or all gate methods in Qrack ultimately call Mtrx(), Phase(), or Invert(), or their controlled variants, at base. Hence, gate "shortcuts" like Pauli X/Y/Z, H, S, T, and others only define a constant vector of 2 or 4 complex numbers that correspond to the named gate operator and call Mtrx()/Phase()/Invert(). Typically, such methods would be good candidates for inline compilation.

This release moves these "shortcuts" out of a module and into the QInterface header, giving the compiler the opportunity to make them inline. Judging by the slightly increased binary size, this leads to significant additional inline method calls, as compiled. Making methods inline can have varied and counterintuitive effects on speed and binary size, but, for the increased binary size, calls to "shortcut" gates are likely a tiny bit faster and of a higher likelihood to be optimized together with other code at different scopes, by the compiler.

This release also fixes edge cases in PhaseRootN() variants that have been present and sub-optimal for years.

v0.21.15 still had significant edge cases in QBdt/QStabilizerHybrid interoperability that led to segmentation faults; this release, v0.21.16, fixes edge cases for the layer combination, in random mirror circuit tests.

This release fixes an edge case that could cause QBdt with QStabilizerHybrid interoperability to throw a segmentation fault. (It also slightly optimizes edge cases in composing QStabilizerHybrid subsystems that might or might not have ancillary qubits.)

Interoperability between QBdt and other "layers" of Qrack has been fixed, (except for state vector simulation "under" QBdt, which has been temporarily disabled). This release allows one to use QUnit, QUnitMulti, QStabilizerHbrid, and QBdt simultaneously in concert, in the same simulator.

Relative the preview release, v0.21.13 fixes a couple of minor issues in code, and a big issue with the packaging of v0.21.12:

• Very long control qubit index vectors (typically >256 elements) no longer have the potential to cause bitLenInt loops over these vectors to never reach the loop termination condition
• An optimized QEngineCPU overload has been restored for uniformly controlled gates
• In v0.21.12, Windows builds accidentally contained main branch code rather than Qrack API v8, (which is by now on main). Now, all binaries are built from the same API v8 code, short hash b73690e.

This release uses a preview version of the Qrack v8 API! The public PyQrack API is not changed, and most users won't notice a difference. However, the general point of Qrack v8 is to take lessons about "memory safety" from 5 years of Qrack development.

The biggest (internal) change is that Qrack public API methods no longer accept the combination of a raw (const) pointer and a secondary parameter to specify its length; rather, all such instances for bitLenInt index lists simply accept a const std::vector<bitLenInt>& type argument, to replace both parameters as a set. As a result, (without some very unlikely and "opportune" partial corruption of std::vector container instances,) it should never be possible in statically-linked Qrack to induce the library, with an invalid array length parameter, to read out-of-bounds past the end of the original pointer-to-const parameter. (Performance-critical sections with an exact implicitly known length for pointer parameters, like in direct state vector copying, retain raw pointer-toconst signatures.)

Qrack takes the recent popular and professional discourse surrounding Rust and "memory safety" seriously. More than a quarter million downloads of PyQrack later, the PyQrack developers can assert with confidence due to our track record in field deployment that double-free, access-after-free, memory leaks, and concurrency errors are typically nil, in any given iteration of the Qrack binaries under PyQrack. However, that doesn't mean we can't learn and benefit from past mistakes and new designs! The parameter patterns that Qrack v8 replaces, going back to the absolute earliest days of Qrack, have by now proven to be wholly an anti-pattern, with no particular benefit and at least one obvious problem. PyQrack users never directly interfaced with this anti-pattern anyway, but sleep soundly knowing that internal use of "lists" of qubit indices are bounds-checked for both the index "list" container and the subsequent OpenCL access patterns for which they code! (You rock!)

Sorry to spam releases again, but it very quickly occurred to me that I had missed cases of "memory safety" with regard to duplicate controls in ALU and other methods, as opposed to just elementary controlled gates in v0.21.10. Also, I updated my build environments, and Boost header versions were updated for Mac/Windows.

As lead developer of Qrack and PyQrack, I have already admitted that there is a real reason to prioritize "memory safety" in a sense comparable to Rust, with which it might not be feasible to achieve exact parity, but at least a specific round of changes should be made to avoid obvious segmentation faults.

In this release, building on previous releases that prevented requesting any qubits outside of the range of allocated qubits in a simulator, it is now also not possible without raising exception to specify the same control or target qubit more than once in the same gate, which would result in undefined behavior. Before this release, it might have been possible to cause OpenCL kernels and CPU equivalents to left-shift for an indefinite number of increments by specifying repeated control qubits, leading to potential out-of-bounds heap access attempts. Instead, the user now receives a std::invalid_argument exception before the out-of-bounds access is attempted, (translated to a Python exception, in PyQrack).

(Qrack v8 is planned to continue prioritizing manual memory safeguards like these. However, on an aside, when the statically-linked C++11 Qrack API accepts read-only complex type pointers with implicit array length, I suspect this greatly benefits FORTRAN LAPACK interface, as opposed to std::vector-based implementations or similar, and so maybe we should compromise for the sake of performance when it is acceptably "safe enough.")

List initializers were also brought up to a better code standard in this release, though no warnings or errors surfaced as a result of the conversion, so this difference is likely more-or-less inconsequential.

In the course of preparing an alternate back end implementation, (with that back end not in this release,) various small imperfections became apparent in OCLEngine and QEngineOCL. Though a number of deviations from Qrack standards were corrected, only two changes in particular are likely to ever be noticed: a minor segmentation fault edge case was corrected in OpenCL callback usage, and QEngine::clDump() was modified to correctly track OpenCL memory usage for limits enforcement, whereas it previously relied on the destructor of QEngineOCL and might have missed more edge cases.

Unused declarations were also removed from OpenCL kernels, but no significant performance difference is likely. However, re-compile your OpenCL kernels, if you use qrack_cl_precompile.

A significant bottleneck in QPager simulations has been fixed: it is not always necessary to pin host memory for copying GPU-to-GPU in Compose(). This improves the case of Compose() with multiple GPUs that are in the same OpenCL "platform," (as would commonly be the case for 2 or 4 homogeneous GPUs in the same node, for example).

More checks have been added for whether requested qubit indices are out-of-bounds, in the underlying Qrack API. We can't guarantee unconditional "memory safety," as PyQrack is based upon a shared library C interface that accepts array parameters, for which it is dependent on separate array length parameters to know the allocated length of those array parameters. However, the goal is that, if QrackSimulator is given bad method arguments, PyQrack should still never raise a segmentation fault. These improvements (and particularly the related domain checks added in v0.21.7) should also act as a first line of defense against OpenCL buffer overrun.

Underlying QEngineCPU, QEngineOCL, QStabilizer, and QBdt types now check to make sure that qubit index arguments do not exceed the allocated number of qubits in a simulator. If they do, std::invalid_argument is raised by Qrack (and caught in the shared library C API, and re-thrown at Python level).

Historically, it turns out that the developer misunderstood C++ const pointer semantics, and const pointer* arguments have been made pointer const* arguments, as was originally intended. (The former is a pointer that is itself constant, as opposed to the latter meaning a pointer to memory that will not be modified.)

A redundant call to check probability in TrySeparate() was also removed, which increases performance.

(QBdt debugging is still underway, though use cases that don't mix quantum binary decision tree qubits with ket qubits under QBdt might already work, as either fully "QBDT" qubits or fully ket qubits.)

With this release, QBdt ("quantum binary decision tree") passes all unit tests, both with and without "attached" ket qubits, and both with and without QUnit or QUnitMulti layer operating on top.

(We previously advertised that QBdt would become part of the default optimal stack, but there were still bugs at that time that interfered with benchmarks, and we have rolled back that change. However, the same effect can be achieved by turning the QBdt layer on in any layer stack and configuring it with the appropriate environment variables from the Qrack README.)

This release is only various micro-optimizations and one edge case bug fix:

• An edge case bug of QPager::Compose() was fixed, where qubit count was not previously correctly updated.
• In the more general case, QPager::Compose() has been made greedier, to sooner free memory with which it is finished, which might reduce the peaks of QPager memory-usage spikes.
• Micro-optimizations were made in the OpenCL program. If you precompile OpenCL kernels, recompile your kernels, for this release!
• A (blocking) clFinish() call in QEngineOCL::DecomposeDispose() was assessed to be unnecessary and removed, which might give a tiny improvement to the parallelism of internal and public API Dispose() calls.

Again, note that If you precompile OpenCL kernels, recompile your kernels, for this release! (I would guess that the old OpenCL program might be 100% functional anyway, but you would likely prefer to have the benefit of the new OpenCL micro-optimizations.)

This release fixes the proactive distribution of load over devices in QPager::Compose(), which allows it to work under QUnit, (as on a local test system with a NVIDIA RTX 3080 and an Intel HD, for one additional qubit over that attainable with just the RTX 3080).

This release fixes a segmentation fault in the QUnit over QStabilizerHybrid layer stack.

We seem to run into significantly fewer memory safety errors in high-width benchmarks, by replacing the use of (C++) std::vector<QEnginePtr>.push_back() in iteration over state vectors with a pre-allocated vector of NULL pointers.

After having debugged QPager, many systems seem significantly more susceptible to "hanging" on high-width circuits. To alleviate this, devices default to a memory usage limit of 3/4 of their global RAM, (usually equivalent to 3 out of 4 maximum allocation segments). This allocation limit can be turned up or down, per device, with the environment variable QRACK_MAX_ALLOC_MB. (Also consider setting QRACK_MAX_PAGING_QB.)

With v0.21.0, apparent QPager performance was significantly reduced, though the results are more correct, so a comparison to the previous bugged implementation might not be fair. However, we have prioritized improving performance in the new implementation.

v0.21.1 has about a 10% improvement in overall execution time for a representative 30 qubit QFT on an RTX 3080 GPU using QUnit.

QPager in the underlying Qrack library, for multi-device or multi-allocation-segment simulation, has been extensively debugged. Its apparent performance might suffer on multi-page loads, but the tradeoff is that its results are now reliable correct, comparatively.

QMaskFusion layer has been totally removed from Qrack, and the corresponding is1QbFusion PyQrack layer option with it. The intent of QMaskFusion is still accomplished by mx(), my(), and mz(), but the layer that automatically composes these operations out of x(), y(), and z() calls provides no practical benefit, under any circumstances ever observed.

QBdt now takes QHybrid as its default base simulator type, allowing it to take advantage of QEngineCPU for low-width simulations while scaling to QBdt-based qubits as a replacement for QPager.

QBdt is now part of the default optimal stack, without an opt-in environment variable. To opt-out of using QBdt as part of default optimal stack, set QRACK_QPAGER_DEVICES=-2, or set QRACK_QPAGER_DEVICES to any set of devices you intend. (The special device ID value -2 indicates that QInterface-local default device should be used, as opposed to -1 for global default device. -2 will not interfere with the distribution of QUnitMulti, for example, hence this is effectively already the default setting for QRACK_QPAGER_DEVICES, except for QBdt usage choice.)

Notably, this release fixes the version check logic for GNU libc. It also cuts some "junk" out of the C++ code for QUnitMulti and QStabilizerHybrid. (My hope is to use this version as a reference for my own benchmarks.)

Sorry for the rapid-fire releases, but the past 12 to 24 hours have seen a flurry of activity that I might consider a "breakthrough" in multiple OpenCL device simulation. In this release, very old code was cut in the QStabilizerHybrid constructor in the default optimization layer stack, removing a redundant layer of QPager. ARM binaries have also been fixed, to use shortcuts instead of a duplicate file for shared library aliases, which should reduce wheel sizes.

Continuing the work from last night in v0.20.2, QUnitMulti stack selection edge cases have been fixed, for proactive OpenCL device distribution. Automatic device redistribution is totally avoided unless explicitly enabled when a QEngineOCL exists at the bottom of the layer stack, as opposed to QHybrid, which can switch device designations for free before crossing the CPU-to-GPU threshold.

QUnitMulti in C++ Qrack has been significantly revised. As a result, proactive distribution to multiple devices is better.

If your throughput suffers as a result of this version upgrade, first try switching isSchmidtDecomposeMulti=False in your QrackSimulator constructor. Realize that if you have two heterogeneous devices, like a primary GPU and an integrated graphics accelerator, then the smaller accelerator's throughput would be less, but its memory capacity might be more than the primary GPU.

Additional control of multiple OpenCL device systems can be modulated through virtualization environments, like VirtualCL or SnuCL.

This release tunes QBdt defaults. (QBdt is still included in the default stack only with QRACK_QBDT_DEFAULT_OPT_IN environment variable set truthy.) QRACK_SEGMENT_QBDT_QB now controls the paging segment size relative max single QEngineOCL qubit allocation, and its default value is 5, (for 5 page segment powers, plus 2 global qubits over 4 pages of a GPU).

QBdt ("quantum binary decision tree") has finally been made production-ready. (I considered it experimental, in all previous versions.) As a Qrack layer, it fully interoperates with QUnitMulti and QStabilizerHybrid. Although it is not intended for use with QPager, commonly, it can replace QPager as a single-device "paged" simulation, (commonly for 4 pages on an NVIDIA device), by using as many "global qubits" as QPager.

The place of QBdt in the default empty stack (from fully default QrackSimulator constructor Boolean options) is as a replacement for QPager layer only when no QPager device list is specified by environment variable. However, for the first release with this default layer change, one must manually opt-in to the change by setting environment variable QRACK_QBDT_DEFAULT_OPT_IN to any truthy value. (For example, on a Linux system, export QRACK_QBDT_DEFAULT_OPT_IN=1 at command line to turn the option on for the current terminal session.)

By default, QBdt will offload a single device maximum allocation segment to ket simulation. Ket is simply faster in this role, for now, but the two freely interoperate, as with a permeable domain wall between the two methods, but the domain wall is not necessarily managed by module user's code. As QBdt can act analogously to QPager this way, single device QBdt instances at maximum capacity will typically have two QBdt method qubits in lowest significance indices, which can be leveraged to specific purposes for their algorithmic strengths. To add relatively more QBdt method qubits than just two per device, select the count of extra qubits to add by setting environment variable QRACK_SEGMENT_GLOBAL_QB to that integer. (This environment variable does the same thing for QPager.)

(Special thanks to Jülich Supercomputing Centre and researchers including Robert Wille, re: your presentation at IEEE Quantum Week, 2021! See for example: https://arxiv.org/abs/2108.07027)

A bug in QUnit::ISwap() gate has been fixed, by removing the SWAP_IDENT() macro from QUnit.

A minor bug has been fixed in stabilizer ISwap(), in the underlying Qrack library. Default decomposition of ISwap() has also been simplified.