Commit e9fff073 authored by Mccaskey, Alex's avatar Mccaskey, Alex
Browse files

updating read the docs

parent 8e89313f
......@@ -3,3 +3,22 @@
XACC API
=========
Kernels
--------
Compilers
----------
Intermediate Representation
----------------------------
IR Transformations
-------------------
Accelerators
-------------
Programs
---------
......@@ -7,12 +7,14 @@ Welcome to XACC's documentation!
================================
.. toctree::
:maxdepth: 2
:maxdepth: 3
:caption: Contents:
overview
install
api
plugins
tutorials
Indices and tables
==================
......
......@@ -15,48 +15,250 @@ The following third party libraries (TPLs) are used by XACC:
+------------------------+------------+-----------+
| Boost | Required | 1.59.0+ |
+------------------------+------------+-----------+
| CppMicroServices | Required | 3.1 |
+------------------------+------------+-----------+
| CppRestSDK | Optional | 2.9+ |
+------------------------+------------+-----------+
| OpenSSL | Optional | 1.0+ |
+------------------------+------------+-----------+
| MPI | Optional | N/A |
+------------------------+------------+-----------+
| Python-Devel | Optional | 2.7 |
+------------------------+------------+-----------+
Note that you must have a C++14 compliant compiler.
For GCC, this means version 6.1+, for Clang, this means 3.4+.
Also note that CppRestSDK is optional. XACC uses this
library for remote interacting with remotely hosted
quantum resources. If you choose not to include this
library in your XACC build, you will not have access
to the Rigetti, D-Wave, or IBM Accelerators. If you
choose to include CppRestSDK you must also install OpenSSL.
Build XACC
-----------
To build the Python XACC API, you must also have
installed the python development library and headers.
Clone the XACC repository:
You can build these dependencies with the `Spack
<https://github.com/llnl/spack>`_ package manager. Configure
your available system compilers by running
.. code::
$ git clone https://github.com/ornl-qci/xacc
XACC requires CMake 3.2+ to build. Run the following to
configure and build XACC:
.. code::
$ cd xacc && mkdir build && cd build
$ cmake ..
$ make install # can pass -jN for N = number of threads to use
This will install XACC to /usr/local/xacc
(Pass -DCMAKE_INSTALL_PREFIX=$YOURINSTALLPATH to install it somewhere else).
Set your PATH variable to include the XACC bin directory:
.. code::
$ export PATH=/usr/local/xacc/bin:$PATH
Additionally, you could add this to your home directory's .basrhc file (or equivalent).
Installing XACC Plugins
-----------------------------------
If you have successfully built XACC (see above)
then you can now run
.. code::
$ xacc-install-plugins.py --help
This is a convenience python script to help download, build, and install
all currently supported XACC plugins. The execution syntax is as follows:
.. code::
$ xacc-install-plugins.py -p PLUGIN-NAME
You can also run this script with multiple plugin names.
Let's see how to use this script to install the
Rigetti, IBM, TNQVM, Scaffold, D-Wave, and Python plugins.
.. note::
If you want support for the IBM, D-Wave, and Rigetti Accelerators, you must install
`CppRestSDK <https://github.com/microsoft/cpprestsdk>`_ and OpenSSL. This
is required for these Accelerators to make remote HTTP Rest calls to their
respective server APIs. Here's how to install these as binaries on various popular platforms:
.. code::
$ (macosx) brew install cpprestsdk
$ (fedora) dnf install cpprest-devel openssl-devel
$ (ubuntu) apt-get install libcpprest-dev libssl-dev
Rigetti Support
^^^^^^^^^^^^^^^^
The `Rigetti Plugin <https://github.com/ornl-qci/xacc-rigetti>`_ provides
support to XACC for compiling kernels writting in Quil, and executing programs
on the Rigetti QVM via a Rigetti Accelerator.
To install this plugin, run the following
.. code::
$ xacc-install-plugins.py -p xacc-rigetti
You have now installed the Rigetti plugin. It is located in $XACC_ROOT/lib/plugins/accelerator
and $XACC_ROOT/lib/plugins/compilers, where XACC_ROOT is your XACC install prefix.
IBM Support
^^^^^^^^^^^^^
The `IBM Plugin <https://github.com/ornl-qci/xacc-ibm>`_ provides
support to XACC for executing programs
on the IBM Quantum Experience via the IBM Accelerator.
To install this plugin, run the following
.. code::
$ xacc-install-plugins.py -p xacc-ibm
You have now installed the IBM plugin. It is located in $XACC_ROOT/lib/plugins/accelerator,
where XACC_ROOT is your XACC install prefix.
TNQVM
^^^^^^^
The `TNQVM Plugin <https://github.com/ornl-qci/tnqvm>`_ provides
support to XACC for executing programs
on the ORNL tensor network quantum virtual machine.
.. note::
This Accelerator requires BLAS/LAPACK libraries to be installed.
Here's how to install these as binaries on various popular platforms:
.. code::
$ (macosx) should already be there in Accelerate Framework, if not
$ (macosx) brew install openblas lapack
$ (fedora) dnf install blas-devel lapack-devel
$ (ubuntu) apt-get install libblas-dev liblapack-dev
To install this plugin, run the following
.. code::
$ xacc-install-plugins.py -p tnqvm
You have now installed the TNQVM plugin. It is located in $XACC_ROOT/lib/plugins/accelerator,
where XACC_ROOT is your XACC install prefix.
Scaffold Support
^^^^^^^^^^^^^^^^^
.. note::
Due to issues getting `ScaffCC <https://github.com/ornl-qci/ScaffCC>`_ to link correctly with RTTI on Mac OS X, we do not have a binary package installer for Mac OS X. We are open to PRs on this if you can help.
To use the `Scaffold Plugin <https://github.com/ornl-qci/tnqvm>`_ you must have our fork of
Scaffold installed as a binary package. We have builds for Fedora 25/26 and Ubuntu 16.04/17.04. To
install
.. code::
$ (fedora) dnf install https://github.com/ORNL-QCI/ScaffCC/releases/download/v2.0/scaffold-2.0-1.fc25.x86_64.rpm (REPLACE 25 with 26 if on FC26)
$ (ubuntu) wget https://github.com/ORNL-QCI/ScaffCC/releases/download/v2.0/scaffold_2.0_amd64.deb
$ (ubuntu) apt-get install -y $(dpkg --info scaffold_2.0_amd64.deb | grep Depends | sed "s/.*ends:\ //" | sed 's/,//g')
$ (ubuntu) dpkg -i scaffold_2.0_amd64.deb
To install this plugin, run the following
.. code::
$ xacc-install-plugins.py -p xacc-scaffold
You have now installed the Scaffold plugin. It is located in $XACC_ROOT/lib/plugins/compilers,
where XACC_ROOT is your XACC install prefix.
D-Wave Support
^^^^^^^^^^^^^^^
The `D-Wave Plugin <https://github.com/ornl-qci/xacc-dwave>`_ provides
support to XACC for executing programs
on the D-Wave QPU via the D-Wave Accelerator.
To install this plugin, run the following
.. code::
$ xacc-install-plugins.py -p xacc-dwave
You have now installed the D-Wave plugin. It is located in $XACC_ROOT/lib/plugins/accelerator,
where XACC_ROOT is your XACC install prefix.
Furthermore, XACC has extensibility built in for minor graph embedding
algorithms. We currently have one supported embedding algorithm, a wrapper around
the D-Wave SAPI Cai, Macready, Roi algorithm. In order to install this as a plugin,
run the following
.. note::
The following embedding algorithm needs to leverage the proprietary
D-Wave SAPI header file and associated shared library: dwave_sapi.h and libdwave_sapi.so.
In order for the installation below to work, place dwave_sapi.h in /usr/local/include/
and libdwave_sapi.so in /usr/local/lib/
.. code::
$ xacc-install-plugins.py -p xacc-dwave-sapi-embedding
You have now installed the D-Wave plugin. It is located in $XACC_ROOT/lib/plugins/accelerator
and $XACC_ROOT/lib/plugins/compilers, where XACC_ROOT is your XACC install prefix.
Python Bindings
^^^^^^^^^^^^^^^^
The `Python Plugin <https://github.com/ornl-qci/xacc-python>`_ provides
Python language bindings to XACC through the `pybind11 <https://github.com/pybind/pybind11>`_ project.
.. note::
This plugin requires Python 2.7+ development headers/library.
Here's how to install these on various popular platforms:
.. code::
$ (macosx) brew install python
$ (fedora) dnf install python-devel
$ (ubuntu) apt-get install python-dev
To install this plugin, run the following
.. code::
$ xacc-install-plugins.py -p xacc-python
You have now installed the Python plugin. It is located in $XACC_ROOT/lib/python,
where XACC_ROOT is your XACC install prefix.
In order to use this installation, you must update your PYTHONPATH environment variable
.. code::
$ export PYTHONPATH=$XACC_ROOT/lib/python:$PYTHONPATH
We recommend placing this command in your home directory's .bashrc file (or equivalent).
XACC and Spack
---------------
You can build XACC and its dependencies with the `Spack
<https://github.com/llnl/spack>`_ package manager.
To configure your available system compilers run
.. code::
$ spack compilers
.. note::
If you run 'spack config get compilers' and your desired
compiler has fc and f77 set to Null or None, then the
install will not work. If this is the case, it usually
works to run 'spack config edit compilers' and
If you run 'spack config get compilers' and your desired
compiler has fc and f77 set to Null or None, then the
install will not work if you are including MPI support.
If this is the case, it usually
works to run 'spack config edit compilers' and
manually replace Null with /path/to/your/gfortran
We will rely on the environment-modules package to load/unload
installed Spack modules. If you don't have this installed
(you can check by running 'module avail') install with
We will rely on the environment-modules package to load/unload
installed Spack modules. If you don't have this installed
(you can check by running 'module avail') install with
.. code::
......@@ -68,8 +270,8 @@ Add the following to your ~/.bashrc (or equivalent)
. $SPACK_ROOT/share/spack/setup-env.sh
source $(spack location -i environment-modules)/Modules/init/bash
If you do not have a C++14 compliant compiler, you can
If you do not have a C++14 compliant compiler, you can
install one with Spack, for example
.. code::
......@@ -78,61 +280,32 @@ install one with Spack, for example
$ spack load gcc
$ spack compiler find
Now install the dependencies with your specified C++14 compiler (mine
Now install the dependencies with your specified C++14 compiler (mine
will be gcc 7.2.0)
.. code::
$ spack install boost+mpi+graph ^mpich %gcc@7.2.0
$ spack install python %gcc@7.2.0
$ spack install cpprestsdk %gcc@7.2.0
CppMicroServices has not yet been accepted into the Spack (we will soon issue a PR
to get it shipped as part of Spack). So in order to install it with Spack
$ (with MPI support) spack install boost+mpi+graph ^mpich %gcc@7.2.0
$ (without MPI support) spack install boost+graph %gcc@7.2.0
XACC has not yet been accepted into the Spack (we will soon issue a PR
to get it shipped as part of Spack). So in order to install it with Spack
we have to download our custom package recipe from the XACC repository:
.. code::
$ cd $SPACK_ROOT/var/spack/repos/builtin/packages/ && mkdir cppmicroservices
$ cd cppmicroservices && wget https://github.com/ORNL-QCI/xacc/raw/master/cmake/spack/cppmicroservices/package.py .
$ cd $SPACK_ROOT/var/spack/repos/builtin/packages/ && mkdir xacc
$ cd xacc && wget https://github.com/ORNL-QCI/xacc/raw/master/cmake/spack/xacc/package.py .
Now we can run
Now we can run
.. code::
$ spack install cppmicroservices %gcc@7.2.0
$ spack install xacc %gcc@7.2.0
Once all these are installed, load them as environment modules
Once all these are installed, load them as environment modules
so they are available for the XACC build:
.. code::
$ spack load cppmicroservices
$ spack load boost
$ spack load python
$ spack load cpprestsdk
Build XACC
-----------
Clone the XACC repository:
.. code::
$ git clone https://github.com/ornl-qci/xacc
XACC requires CMake 2.8+ to build. Run the following to
configure and build XACC:
.. code::
$ cd xacc && mkdir build && cd build
$ cmake ..
$ make install # can pass -jN for N = number of threads to use
$ ctest
This will install XACC to /usr/local/xacc. Since we built with
CppRestSDK/OpenSSL, we have the Rigetti and D-Wave Accelerators
installed. Since we build with Python, we also have
/usr/local/xacc/lib/python/pyxacc.so which contains the
XACC Python API.
......@@ -12,6 +12,10 @@ To achieve this interoperability, XACC defines four primary abstractions or conc
XACC has support for a number of languages and physical and virtual hardware instances. XACC provides a Compiler realization that enables quantum kernel programming in the Scaffold programming language - an effort that came out of the IARPA QCS program. This compiler leverages the Clang/LLVM library extensions developed under that project that extend the LLVM IR with quantum gate operations. XACC extends this compiler with support for new constructs, like custom quantum functions and source-to-source translations (mapping Scaffold to other languages). XACC provides an Accelerator realization that enables execution of quantum kernels in any available language for both the Rigetti Quantum Virtual Machine (QVM, Forest API) and the physical two qubit (pyquillow) Rigetti QPU. These Accelerators map the XACC IR to Quil (the Rigetti low-level assembly language) and leverage an HTTP Rest client to post compiled quantum kernel code to the Rigetti QVM/QPU driver servers. XACC also has support for the D-Wave QPU, which demonstrates the wide applicability of this heterogeneous hybrid programming model across quantum computing models. XACC has Compiler and Accelerator realizations that enable minor graph embedding of binary optimization problems and execution on the D-Wave Qubist QPU driver server, respectively.
XACC Plugin Infrastructure
---------------------------
XACC relies on a project called `CppMicroServices <http://github.com/cppmicroservices/cppmicroservices>`_ - a native C++ implementation of the OSGi specification that enables an extensible plugin infrastructure for compilers and accelerators. As such, installation of XACC provides the core infrastructure for describing Programs, Compilers, Accelerators, and IR. To enable support for various compilers and accelerators (like the Scaffold or Quil compilers, or the IBM or Rigetti QPUs) you must install the appropriate plugin (see `XACC Plugins <plugins.html>`_).
XACC Development Team
----------------------
......@@ -23,9 +27,6 @@ XACC is developed and maintained by:
* `Dmitry Liakh <liakhdi@ornl.gov>`_
* `Mengsu Chen <mschen@vt.edu>`_
XACC Packages
--------------
Questions, Bug Reporting, and Issue Tracking
---------------------------------------------
......
XACC Plugins
=============
Rigetti
--------
Rigetti Computing, Inc (`rigetti.com <rigetti.com>`_) is a recently founded startup that is focused on
developing quantum computing hardware and software and bring it to market.
They are working to build a cloud quantum computing platform for AI and
computational chemistry. They currently have a QVM simulation server
that can be accessed via a REST API with a private API key. Rigetti has
also done great work as of late in providing open source programming tools for
interfacing with their QVM - specifically, the PyQuil python framework
`PyQuil <https://github.com/rigetticomputing/pyquil>`_.
Recently, the ORNL QCI `(quantum.ornl.gov) <http://quantum.ornl.gov>`_, the XACC project,
and the Software and Applications Team from Rigetti have begun collaborating in
an effort to expose the Rigetti QVM server and programming tools to XACC and its user
community. This article describes the results of that work - specifically, a
new XACC Accelerator implementation that executes quantum kernels on the
Rigetti QVM server. For a more hands-on tutorial on how to use XACC and the Rigetti
Accelerator, check out `Rigetti Tutorial <tutorials.html#Rigetti QVM Tutorial>`_).
RigettiAccelerator
^^^^^^^^^^^^^^^^^^^
The RigettiAccelerator is an implementation or realization of the pluggable
XACC Accelerator interface. The RigettAccelerator class architecture diagram is
shown in Figure 1. The RigettiAccelerator's implementation of the Accelerator::execute() method
is charged with two primary tasks: (1) the translation of the XACC IR to an equivalent
Quil string, and (2) constructing and executing an
appropriate HTTPS Post on the Rigetti QVM server. The only remaining
thing to do once those two tasks are complete is to processes the resultant response from the server.
.. image:: ../../assets/rigetti-acc-arch.png
Mapping XACC IR to Quil
^^^^^^^^^^^^^^^^^^^^^^^^
Basically,
at its core, the XACC IR provides a tree-like, in-memory representation and API for a
compiled quantum kernel. The leaves of this tree are XACC Instructions and the nodes
of the tree are XACC Functions, which are composed of further child Instructions. The
XACC Quantum IR implementation provides a number of standard gate Instruction implementations
(Hadamard, CNOT, rotations, etc...) These serve as the leaves of the IR tree. These
instruction implementations know nothing of the Quil intermediate language and it would be tedious
and a poor design decision to to update the entire XACC Quantum IR package (we would have to do the
same for any and all current and future low-level languages). So XACC employs a common
software engineering design pattern to enable this XACC IR to Quil mapping: the
visitor pattern, which provides a mechansim for adding new operations to an
existing object without modifying the design of that object (`Visitor Pattern <https://en.wikipedia.org/wiki/Visitor_pattern>`_). For each derived gate Instruction, a Visitor class implements a
corresponding ```visit``` method (```visit(Hadamard& h)```, etc...). All gate instructions have the
ability to accept an incoming Visitor, and upon doing so, invoke the ```visit``` method that
corresponds to their type, thus giving the Visitor type information for the Gate Instruction.
Therefore, mapping to Quil simply involves walking the IR tree, and telling each Instruction to
accept the visitor:
.. code::
auto visitor = std::make_shared<QuilVisitor>();
InstructionIterator it(kernel);
while (it.hasNext()) {
// Get the next node in the tree
auto nextInst = it.next();
if (nextInst->isEnabled()) nextInst->accept(visitor);
}
auto quilStr = visitor->getQuilString();
The visitor implementation is known as the QuilVisitor, and its visit methods look like this (Hadamard for example):
.. code::
void visit(Hadamard& h) {
quilStr += "H " + std::to_string(h.bits()[0]) + "\n";
}
or for a more complicated gate Instruction:
.. code::
void visit(ConditionalFunction& c) {
auto visitor = std::make_shared<QuilVisitor>();
auto classicalBitIdx = qubitToClassicalBitIndex[c.getConditionalQubit()]; // populated in visit(Measure)
quilStr += "JUMP-UNLESS @" + c.getName() + " [" + std::to_string(classicalBitIdx) + "]\n";
for (auto inst : c.getInstructions()) {
inst->accept(visitor);
}
quilStr += visitor->getQuilString();
quilStr += "LABEL @" + c.getName() + "\n";
}
After walking the IR tree, the Quil representation is produced with a call to getQuilString().
Executing Quil code on Rigetti QVM
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
With the XACC IR mapped to Quil, the RigettiAccelerator is ready to execute
on the Rigetti QVM. The main task here is to construct the proper JSON payload string
that contains information about the type of the execution, the classical memory address
indices, and the Quil instructions string. The types of execution that the QVM allows are
multishot, multishot-measure, wavefunction, and expectation. In this work, we have primarily focused
on the multishot method. If the execution type is
multishot, then we can provide a further JSON key that is an integer that gives the
number of executions of the Quil code to run.
IBM
----
D-Wave
-------
Scaffold
---------
TNQVM
------
Python
------ -
XACC and Spack
===============
You can build these dependencies with the `Spack
<https://github.com/llnl/spack>`_ package manager. Configure
your available system compilers by running
.. code::
$ spack compilers
.. note::
If you run 'spack config get compilers' and your desired
compiler has fc and f77 set to Null or None, then the
install will not work if you are including MPI support.
If this is the case, it usually
works to run 'spack config edit compilers' and
manually replace Null with /path/to/your/gfortran
We will rely on the environment-modules package to load/unload
installed Spack modules. If you don't have this installed
(you can check by running 'module avail') install with
.. code::
$ spack install environment-modules
Add the following to your ~/.bashrc (or equivalent)
.. code::
. $SPACK_ROOT/share/spack/setup-env.sh
source $(spack location -i environment-modules)/Modules/init/bash
If you do not have a C++14 compliant compiler, you can
install one with Spack, for example
.. code::
$ spack install gcc@7.2.0 # this will take awhile...
$ spack load gcc
$ spack compiler find
Now install the dependencies with your specified C++14 compiler (mine
will be gcc 7.2.0)
.. code::
$ (with MPI support) spack install boost+mpi+graph ^mpich %gcc@7.2.0
$ (without MPI support) spack install boost+graph %gcc@7.2.0
XACC has not yet been accepted into the Spack (we will soon issue a PR
to get it shipped as part of Spack). So in order to install it with Spack
we have to download our custom package recipe from the XACC repository:
.. code::
$ cd $SPACK_ROOT/var/spack/repos/builtin/packages/ && mkdir xacc
$ cd xacc && wget https://github.com/ORNL-QCI/xacc/raw/master/cmake/spack/xacc/package.py .
Now we can run
.. code::
$ spack install xacc %gcc@7.2.0
Once all these are installed, load them as environment modules
so they are available for the XACC build:
.. code::
$ spack load boost
XACC Tutorials
================
First off, make sure you have successfully built XACC (see `XACC Install <install.html>`_).
Rigetti QVM Tutorial
---------------------
Create a new directory called test-xacc-rigetti and cd into it. Let's now create a
test-xacc-rigetti.cpp file and get it started with the following boilerplate code:
.. code::
#include "XACC.hpp"