Pyqrack

Recent performance improvements uncovered a deadlock condition (which was longstanding, but previously rarely encountered) in the asynchronous CPU dispatch. This has been fixed and tested in the underlying C++ library.

One OpenCL call that was missed is now also being checked for success and retried on failure, which should cover _all_ OpenCL API calls.

`QEngineOCL::ShuffleBuffers()` has been made asynchronous, significantly simplifying the code in `QPager` that relies on it.

User Zshan0 has kindly contributed a vetted API reference for PyQrack!

Certain OpenCL Qrack internals have been made asynchronous. Improvements have been made in OpenCL error handling, including the addition of a retry procedure for OpenCL calls.

(I swear this is the last _release_ for _today._ Further changes on this topic will be planned ahead, moving forward.)

For PyQrack's role in a larger quantum software stack, we're trying to compromise between the competing demands of not wanting to do _anything_ in Python other than call C interfaces for performance concerns, and meeting the bare minimum support requirements for other software with which we seek to interoperate. v0.17.12 falls a little short of the second goal, hence we iterate immediately.

The Qiskit interpreter method now returns a `list` of measurement samples in hexadecimal notation, exactly as would be expected for the `data` field of a Qiskit experiment results, except without conversion via `Counter()` to a dictionary of counts. This is the _bare minimum_ worst-case execution path that I can momentarily identify, while serving the intended function of sufficiently mirroring the Qiskit API.

If one wants to avoid the sample conversion, I realized, _then it is not necessary to sample the circuit at all_. If one removes measurement at the end of a unitary subroutine, the `QrackSimulator()` should exit Qiskit interpretation in the state expected after the unitary subroutine is finished. At that point, users may run other gates or sample as they wish, which accomplishes the basic aim of v0.17.2, better.

By abstracting Qiskit object conversion methods, and by returning measurement samples in the form most natural and native to PyQrack, we significantly reduce the potential worst-case execution time for circuits compiled with Qiskit. Notably, this adds the function `pyqrack.util.convert_qiskit_circuit_to_qasm_experiment()`, as a potential last step in circuit compilation.

With v0.17.x development, our point is to use the Qiskit compiler to produce optimized circuit definitions that require the absolute minimum of execution time and other computational resources to run. In its most native case, PyQrack can interpret a Python `list` of Qiskit QASM instructions and output a set of samples to match the requested number of trials. We aim for _this_ code path to be directly accessible _after all compilation steps_, where we assume compilation will occur once to be reused many times. Hence, `convert_qiskit_circuit_to_qasm_experiment()` can be used after compilation from a Qiskit `QuantumCircuit` to bring the compiled result into the format that is fastest for PyQrack to interpret. Also, PyQrack measurement outputs follow PyQrack conventions rather than Qiskit conventions, which is faster for PyQrack.

We also offer a separate `qiskit-qrack-provider` package that abides by Qiskit standards for providers. If a user wants full compatibility with Qiskit, they may use that package, but the alternative Qiskit functionality in the PyQrack package itself need not reproduce perfect adherence to Qiskit standards, in the case that a custom PyQrack implementation or convention would be advantageous for speed or other limiting resource improvements. Hence, the PyQrack package now internally provides an alternative for speed, which we assume need not be used with any part of Qiskit but transpilation.

Apologies, in haste and excitement, last night, I forgot to return `counts` at the end of each Qiskit experiment or `QuantumCircuit`. Now, `run_qiskit_circuit()` returns an object with a property `counts` that contains a counter of results from the experiment or circuit. (The Qrack binaries are unchanged from v0.17.0.)