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

updating docs with a few rigetti tutorials

parent 0c2b8e1b
docs/assets/rigetti-acc-arch.png

109 KB | W: | H:

docs/assets/rigetti-acc-arch.png

126 KB | W: | H:

docs/assets/rigetti-acc-arch.png
docs/assets/rigetti-acc-arch.png
docs/assets/rigetti-acc-arch.png
docs/assets/rigetti-acc-arch.png
  • 2-up
  • Swipe
  • Onion skin
D-Wave Integration
===================
Installation
------------
.. note::
If you want support for the D-Wave Accelerator, 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
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`` and ``$XACC_ROOT/lib/plugins/compilers``, where XACC_ROOT is your XACC install prefix.
Extensibility for Minor Graph Embedding Algorithms
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
XACC has extensibility built in for minor graph embedding
algorithms. We currently have one supported embedding algorithm (with more coming online), 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`` (or ``libdwave_sapi.dylib`` on macosx).
In order for the installation below to work, place dwave_sapi.h in ``/usr/local/include/`` and ``libdwave_sapi.so`` or ``libdwave_sapi.dylib`` 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/embedding``, where ``XACC_ROOT`` is your XACC install prefix.
IBM Integration
================
Installation
-------------
.. note::
If you want support for the D-Wave Accelerator, 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
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.
...@@ -13,8 +13,14 @@ Welcome to XACC's documentation! ...@@ -13,8 +13,14 @@ Welcome to XACC's documentation!
overview overview
install install
api api
plugins python
tutorials scaffold
tnqvm
rigetti
ibm
dwave
Indices and tables Indices and tables
================== ==================
......
...@@ -21,6 +21,18 @@ The following third party libraries (TPLs) are used by XACC: ...@@ -21,6 +21,18 @@ The following third party libraries (TPLs) are used by XACC:
Note that you must have a C++14 compliant compiler. Note that you must have a C++14 compliant compiler.
For GCC, this means version 6.1+, for Clang, this means 3.4+. For GCC, this means version 6.1+, for Clang, this means 3.4+.
These dependencies are relatively easy to install on popular operating
systems. Any of the following commands will work (showing with and without MPI):
.. code::
$ (macosx) brew install boost
$ (macosx) brew install boost-mpi
$ (fedora) dnf install boost-devel
$ (fedora) dnf install boost-mpich-devel
$ (fedora) dnf install boost-openmpi-devel
$ (ubuntu) apt-get install libboost-all-dev # will install openmpi
Build XACC Build XACC
----------- -----------
...@@ -33,14 +45,14 @@ Clone the XACC repository: ...@@ -33,14 +45,14 @@ Clone the XACC repository:
XACC requires CMake 3.2+ to build. Run the following to XACC requires CMake 3.2+ to build. Run the following to
configure and build XACC: configure and build XACC:
.. code:: .. code:: bash
$ cd xacc && mkdir build && cd build $ cd xacc && mkdir build && cd build
$ cmake .. $ cmake ..
$ make install # can pass -jN for N = number of threads to use $ make install # can pass -jN for N = number of threads to use
This will install XACC to /usr/local/xacc This will install XACC to ``/usr/local/xacc``
(Pass -DCMAKE_INSTALL_PREFIX=$YOURINSTALLPATH to install it somewhere else). (Pass ``-DCMAKE_INSTALL_PREFIX=$YOURINSTALLPATH`` to install it somewhere else).
Set your PATH variable to include the XACC bin directory: Set your PATH variable to include the XACC bin directory:
...@@ -48,7 +60,7 @@ Set your PATH variable to include the XACC bin directory: ...@@ -48,7 +60,7 @@ Set your PATH variable to include the XACC bin directory:
$ export PATH=/usr/local/xacc/bin:$PATH $ export PATH=/usr/local/xacc/bin:$PATH
Additionally, you could add this to your home directory's .basrhc file (or equivalent). Additionally, you could add this to your home directory's ``.basrhc`` file (or equivalent).
Installing XACC Plugins Installing XACC Plugins
----------------------------------- -----------------------------------
...@@ -68,173 +80,19 @@ all currently supported XACC plugins. The execution syntax is as follows: ...@@ -68,173 +80,19 @@ all currently supported XACC plugins. The execution syntax is as follows:
You can also run this script with multiple plugin names. 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:: .. code::
$ xacc-install-plugins.py -p xacc-scaffold $ xacc-install-plugins.py -p PLUGIN1 PLUGIN2 PLUGIN3
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 You can also pass CMake arguments to this script. For example, if you
wanted to specify the path to your OpenSSL install for a plugin
that depended on OpenSSL, you could run the following
.. code:: .. code::
$ export PYTHONPATH=$XACC_ROOT/lib/python:$PYTHONPATH $ xacc-install-plugins.py -p PLUGIN-NAME -a OPENSSL_ROOT_DIR=/usr/local/opt/openssl
We recommend placing this command in your home directory's .bashrc file (or equivalent). You can pass multiple CMake arguments at once.
XACC and Spack XACC and Spack
--------------- ---------------
......
XACC Python Bindings
=====================
Installation
------------
he `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).
Example Usage
--------------
Suppose you had the Scaffold plugin installed `see here <scaffold.rst>`_, and you wanted to program a simple teleportation code and launch it on TNQVM (see `here <tnqvm.rst>`_ for TNQVM installation details). To program this with the Python XACC bindings you could write the following python script:
.. code::
import pyxacc as xacc
# Create the source code
src = """__qpu__ teleport(qbit qreg){
cbit creg[3];
// qubit0 to be teleported
X(qreg[0]);
// Bell channel set up by qreg[1] and qreg[2]
H(qreg[1]);
CNOT(qreg[1],qreg[2]);
// Alice Bell measurement
CNOT(qreg[0],qreg[1]);
H(qreg[0]);
creg[0] = MeasZ(qreg[0]);
creg[1] = MeasZ(qreg[1]);
// Bob's operation base on Alice's measurement outcome
if (creg[0] == 1) Z(qreg[2]);
if (creg[1] == 1) X(qreg[2]);
}
"""
# Initialize the framework
xacc.Initialize()
# Get reference to our simple accelerator
qpu = xacc.getAccelerator('tnqvm')
# Create some qubits to operate on
qreg = qpu.createBuffer('qreg',3)
# Create the program and build it
p = xacc.Program(qpu, src)
p.build()
# Get the teleport kernel
k = p.getKernel('teleport')
# Execute on qreg with no InstructionParameters
k.execute(qreg, [])
# Display the results to standard out
qreg.printBuffer()
# Finalize the framework
xacc.Finalize()
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment