.. role:: html(raw)
   :format: html

Blackbird Quantum Assembly Language
===================================

:Release: |release|
:Date: |today|

Blackbird is a quantum assembly language for continuous-variable quantum computation, that can be used to program Xanadu's quantum photonics hardware and Strawberry Fields simulator.


Features
--------

The Blackbird repository contains three *separate* packages:

* ``src``: The Blackbird grammar specification in enhanced Brackus-Naur form

* ``blackbird_python``: to develop Blackbird parsers for integration with Python programs

* ``blackbird_cpp``: libraries and header files needed to develop Blackbird
  parsers for integration with C++ programs

All of these packages are independent, and can be installed separately without
depending on one-another. *However*, if the grammar is ever modified, there
is an command for updating the autogenerated parts of the Python and C++
parsers.

In addition, this repository contains:

* ``example``: Example Blackbird scripts

* ``apps``: Example Python/C++ applications using the above parsers


Getting started
---------------

To get the Blackbird grammar installed and running on your system, begin at the :ref:`grammar installation guide <installation>`. Then, familiarize yourself with Blackbird's :ref:`syntax and grammar <syntax>` for specifying photonic quantum circuits. You can even generate Blackbird parsers for any target language supported by ANTLR, including Java, C#, JavaScript, Go, and Swift.

If you only want to develop an application that makes use of the Python parser or the C++ parser, you can go directly to those sections and their corresponding installation guides.


How to cite
-----------


If you are doing research using Blackbird, please cite the `StrawberryFields paper <https://quantum-journal.org/papers/q-2019-03-11-129/>`_:

  Nathan Killoran, Josh Izaac, Nicolás Quesada, Ville Bergholm, Matthew Amy, and Christian Weedbrook.
  "Strawberry Fields: A Software Platform for Photonic Quantum Computing", Quantum, 3, 129 (2019).


Support
-------

- **Source Code:** https://github.com/XanaduAI/Blackbird
- **Issue Tracker:** https://github.com/XanaduAI/Blackbird/issues

If you are having issues, please let us know by posting the issue on our Github issue tracker.

For more details on contributing or performing research with Blackbird, please see
:ref:`research`.


License
-------

Blackbird is **free** and **open source**, released under the Apache License, Version 2.0.


.. toctree::
   :maxdepth: 1
   :caption: Blackbird grammar
   :hidden:

   installing
   syntax
   research

.. toctree::
   :maxdepth: 1
   :caption: Python parser
   :hidden:

   blackbird_python/init
   blackbird_python/installing
   blackbird_python/example
   blackbird_python/program
   blackbird_python/utils
   blackbird_python/listener
   blackbird_python/auxiliary
   blackbird_python/error

.. toctree::
   :maxdepth: 1
   :caption: C++ parser
   :hidden:

   blackbird_cpp/overview
   blackbird_cpp/installing
