.. image:: https://github.com/oqc-community/qat/blob/main/qat-logo.png?raw=True
  :width: 400
  :alt: QAT

.. readme_text_start_label

|

**QAT** (Quantum Assembly Toolkit/Toolchain) is a low-level quantum compiler and runtime which facilitates executing quantum IRs
such as `QASM <https://openqasm.com/>`_, `OpenPulse <https://openqasm.com/language/openpulse.html>`_ and
`QIR <https://devblogs.microsoft.com/qsharp/introducing-quantum-intermediate-representation-qir/>`_ against QPU drivers.
It facilitates the execution of largely-optimised code, converted into abstract pulse-level and hardware-level instructions,
which are then transformed and delivered to an appropriate driver.

For the official QAT documentation, please see `QAT <https://oqc-community.github.io/qat>`_.

|

----------------------
Installation
----------------------

QAT can be installed from `PyPI <https://pypi.org/project/qat-compiler/>`_ via:
:code:`pip install qat-compiler`

|

----------------------
Building from Source
----------------------

We use `poetry <https://python-poetry.org/>`_ for dependency management and run on
`Python 3.10+ <https://www.python.org/downloads/>`_.
Once both of these are installed run this in the root folder to install all the dependencies that you need:
:code:`poetry install`

.. note::
   If you are contributing to the project we recommend that you also run

   :code:`poetry run pre-commit install`
   to enable pre-commit checks.

|

----------------------
Notebooks
----------------------

We use `jupytext https://jupytext.readthedocs.io/en/latest/` to store notebooks in both 'percent' format .py scripts (in notebooks/scripts) and .ipynb jupyter notebooks (in notebooks/ipynb). 

For developers, the notebooks should be synced automatically by pre-commit (which you need to install, see above) and verified automatically in the GitHub pipeline.
They will also be synced automatically on save in jupyterlab. Unfortunately VS code does not sync them automatically on save. They can be manually synced with 
`poetry run jupytext --sync --pipe black notebooks/scripts/*.py`.

----------------------
Roadmap
----------------------

We're currently working on a some significant refactors, we'll be sharing more on this and our future plans soon.


|

----------------------
Contributing
----------------------

To take the first steps towards contributing to QAT, visit our
`contribution <https://github.com/oqc-community/qat/blob/main/CONTRIBUTING.rst>`_ documents, which provides details about our
process.
We also encourage new contributors to familiarise themselves with the
`code of conduct <https://github.com/oqc-community/qat/blob/main/CODE_OF_CONDUCT.rst>`_ and to adhere to these
expectations.

|

----------------------
Where to get help
----------------------

For support, please reach out in the `Discussions <https://github.com/oqc-community/qat/discussions>`_ tab of this repository or file an `issue <https://github.com/oqc-community/qat/issues>`_.

|

----------------------
Licence
----------------------

This code in this repository is licensed under the BSD 3-Clause Licence.
Please see `LICENSE <https://github.com/oqc-community/qat/blob/main/LICENSE>`_ for more information.

|

----------------------
Feedback
----------------------

Please let us know your feedback and any suggestions by reaching out in `Discussions <https://github.com/oqc-community/qat/discussions>`_.
Additionally, to report any concerns or
`code of conduct <https://github.com/oqc-community/qat/blob/main/CODE_OF_CONDUCT.rst>`_ violations please use this
`form <https://docs.google.com/forms/d/e/1FAIpQLSeyEX_txP3JDF3RQrI3R7ilPHV9JcZIyHPwLLlF6Pz7iGnocw/viewform?usp=sf_link>`_.

|

----------------------
Benchmarking
----------------------

The performance of QAT can be measured using our pre-defined benchmarks: :code:`poetry run pytest --benchmark-only`.
To compare to main, checkout the main branch and run :code:`poetry run pytest benchmarks/run.py --benchmark-only --benchmark-save="<benchmark-name>"`. 
Then checkout back to the branch you are working and run :code:`poetry run pytest benchmarks/run.py --benchmark-only --benchmark-save="<benchmark-name>" --benchmark-compare --benchmark-compare-fail=min:50%`.
If the test fails, it might indicate a performance regression: use the comparison table that is outputted to verify.
The performance of pull requests to main will be automatically tested.
See the `pytest-benchmark <https://pytest-benchmark.readthedocs.io/en/latest/usage.html>`_ documentation for more information on how to use it.

|

----------------------
FAQ
----------------------
    Why is this in Python?

Mixture of reasons. Primary one is that v1.0 was an early prototype and since the majority of the quantum community
know Python it was the fastest way to build a system which the most people could contribute to building. The API's would
always stick around anyway, but as time goes on the majority of its internals has been, is being, or will be moved to Rust/C++.

    Where do I get started?

Our tests are a good place to start as they will show you the various ways to run QAT. Running and then stepping
through how it functions is the best way to learn.

We have what's known as an echo model and engine which is used to test QATs functionality when not attached to a QPU.
You'll see these used almost exclusively in the tests, but you can also use this model to see how QAT functions on
larger and more novel architectures.

High-level architectural documents are incoming and will help explain its various concepts at a glance, but
right now aren't complete.

    What OS's does QAT run on?

Windows and Linux are its primary development environments. Most of its code is OS-agnostic but we can't
guarantee it won't have bugs on untried ones. Dependencies are usually where you'll have problems, not the core
QAT code itself.

If you need to make changes to get your OS running feel free to PR them to get them included.

    I don't see anything related to OQC's hardware here!

Certain parts of how we run our QPU have to stay propriety and for our initial release we did not have time to
properly unpick this from things we can happily release. We want to release as much as possible and as you're
reading this are likely busy doing just that.

    Do you have your own simulator?

We have a real-time chip simulator that is used to help test potential changes and their ramifications to hardware.
It focuses on accuracy and testing small-scale changes so should not be considered a general simulator. 3/4 qubit
simulations is its maximum without runtime being prohibitive.
