Commit 71eebc63 authored by Mccaskey, Alex's avatar Mccaskey, Alex
Browse files

Trying to get readthedocs setup

parent cbaedfad
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = python -msphinx
SPHINXPROJ = XACC
SOURCEDIR = source
BUILDDIR = build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
\ No newline at end of file
# Sphinx build info version 1
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
config: 402c5354f3c082e289edf7a69629a8c6
tags: 645f666f9bcd5a90fca523b33c5a78b7
.. meta::
:scope: doxygen
XACC API
=========
.. XACC documentation master file, created by
sphinx-quickstart on Tue Aug 29 20:23:35 2017.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to XACC's documentation!
================================
.. toctree::
:maxdepth: 2
:caption: Contents:
overview
install
api
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
Installation
============
This section provide guidelines for installing XACC and its TPLs.
Install third-party libraries
-----------------------------
The following third party libraries (TPLs) are used by XACC:
+------------------------+------------+-----------+
| Packages | Dependency | Version |
+========================+============+===========+
| C++14 Compiler | Required | See below |
+------------------------+------------+-----------+
| 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.
To build the Python XACC API, you must also have
installed the python development library and headers.
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 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::
$ 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
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 .
Now we can run
.. code::
$ spack install cppmicroservices %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 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.
Getting started with XACC
=========================
Overview
---------
XACC is a programming framework for extreme-scale accelerator architectures that integrates alongside existing conventional classical applications. It is a pluggable framework for programming languages and accelerators developed for next-gen computing hardware architectures like quantum and neuromorphic computing. It lets computational scientists efficiently off-load classically intractable work to attached accelerators through a user-friendly kernel API. XACC makes post-exascale hybrid programming approachable for domain computational scientists.
The XACC programming model, and associated open-source reference implementation, follows the traditional co-processor model, akin to OpenCL or CUDA for GPUs, but takes into account the subtleties and complexities inherent to the interplay between classical and quantum hardware. XACC provides a high-level API that enables classical applications to offload computationally intractable work (represented as quantum kernels) to an attached quantum accelerator in a manner that is agnostic to the quantum programming language and the quantum hardware. This enables one to write quantum code once, and perform benchmarking, verification and validation, and performance studies for a set of virtual (simulators) or physical hardware.
To achieve this interoperability, XACC defines four primary abstractions or concepts: quantum kernels, intermediate representation, compilers, and accelerators. Quantum kernels are C-like functions that contain code intended for execution on the QPU. These kernels are compiled to the XACC intermediate representation (IR), an object model that is key for promoting the integration of a diverse set of languages and hardware. The IR provides four main forms for use by algorithm programmers: (1) an in-memory representation and API, (2) an on-disk persisted representation, (3) human-readable quantum assembly representation, and (4) a control flow graph or quantum circuit representation. This IR is produced by realizations of the XACC compiler concept, which delegates to the kernel language’s appropriate parser, compiler, and optimizer. Finally, XACC IR instances (and therefore programmed kernels) are executed by realizations of the Accelerator concept, which defines an interface for injecting physical or virtual quantum accelerators. Accelerators take this IR as input and delegate execution to vendor-supplied APIs for the QPU (or API for a simulator). The orchestration of these concepts enable an expressive API for quantum acceleration of classical applications.
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 Development Team
----------------------
XACC is developed and maintained by:
* `Alex McCaskey <mccaskeyaj@ornl.gov>`_
* `Travis Humble <humblets@ornl.gov>`_
* `Eugene Dumitrescu <dumitrescuef@ornl.gov>`_
* `Dmitry Liakh <liakhdi@ornl.gov>`_
* `Mengsu Chen <mschen@vt.edu>`_
XACC Packages
--------------
Questions, Bug Reporting, and Issue Tracking
---------------------------------------------
Questions, bug reporting and issue tracking are provided by GitHub. Please
report all bugs by creating a new issue. You can ask questions by creating a
new issue with the question tag.
Publications and Presentations
-------------------------------
/*
* basic.css
* ~~~~~~~~~
*
* Sphinx stylesheet -- basic theme.
*
* :copyright: Copyright 2007-2017 by the Sphinx team, see AUTHORS.
* :license: BSD, see LICENSE for details.
*
*/
/* -- main layout ----------------------------------------------------------- */
div.clearer {
clear: both;
}
/* -- relbar ---------------------------------------------------------------- */
div.related {
width: 100%;
font-size: 90%;
}
div.related h3 {
display: none;
}
div.related ul {
margin: 0;
padding: 0 0 0 10px;
list-style: none;
}
div.related li {
display: inline;
}
div.related li.right {
float: right;
margin-right: 5px;
}
/* -- sidebar --------------------------------------------------------------- */
div.sphinxsidebarwrapper {
padding: 10px 5px 0 10px;
}
div.sphinxsidebar {
float: left;
width: 230px;
margin-left: -100%;
font-size: 90%;
word-wrap: break-word;
overflow-wrap : break-word;
}
div.sphinxsidebar ul {
list-style: none;
}
div.sphinxsidebar ul ul,
div.sphinxsidebar ul.want-points {
margin-left: 20px;
list-style: square;
}
div.sphinxsidebar ul ul {
margin-top: 0;
margin-bottom: 0;
}
div.sphinxsidebar form {
margin-top: 10px;
}
div.sphinxsidebar input {
border: 1px solid #98dbcc;
font-family: sans-serif;
font-size: 1em;
}
div.sphinxsidebar #searchbox input[type="text"] {
width: 170px;
}
img {
border: 0;
max-width: 100%;
}
/* -- search page ----------------------------------------------------------- */
ul.search {
margin: 10px 0 0 20px;
padding: 0;
}
ul.search li {
padding: 5px 0 5px 20px;
background-image: url(file.png);
background-repeat: no-repeat;
background-position: 0 7px;
}
ul.search li a {
font-weight: bold;
}
ul.search li div.context {
color: #888;
margin: 2px 0 0 30px;
text-align: left;
}
ul.keywordmatches li.goodmatch a {
font-weight: bold;
}
/* -- index page ------------------------------------------------------------ */
table.contentstable {
width: 90%;
margin-left: auto;
margin-right: auto;
}
table.contentstable p.biglink {
line-height: 150%;
}
a.biglink {
font-size: 1.3em;
}
span.linkdescr {
font-style: italic;
padding-top: 5px;
font-size: 90%;
}
/* -- general index --------------------------------------------------------- */
table.indextable {
width: 100%;
}
table.indextable td {
text-align: left;
vertical-align: top;
}
table.indextable ul {
margin-top: 0;
margin-bottom: 0;
list-style-type: none;
}
table.indextable > tbody > tr > td > ul {
padding-left: 0em;
}
table.indextable tr.pcap {
height: 10px;
}
table.indextable tr.cap {
margin-top: 10px;
background-color: #f2f2f2;
}
img.toggler {
margin-right: 3px;
margin-top: 3px;
cursor: pointer;
}
div.modindex-jumpbox {
border-top: 1px solid #ddd;
border-bottom: 1px solid #ddd;
margin: 1em 0 1em 0;
padding: 0.4em;
}
div.genindex-jumpbox {
border-top: 1px solid #ddd;
border-bottom: 1px solid #ddd;
margin: 1em 0 1em 0;
padding: 0.4em;
}
/* -- domain module index --------------------------------------------------- */
table.modindextable td {
padding: 2px;
border-collapse: collapse;
}
/* -- general body styles --------------------------------------------------- */
div.body p, div.body dd, div.body li, div.body blockquote {
-moz-hyphens: auto;
-ms-hyphens: auto;
-webkit-hyphens: auto;
hyphens: auto;
}
a.headerlink {
visibility: hidden;
}
h1:hover > a.headerlink,
h2:hover > a.headerlink,
h3:hover > a.headerlink,
h4:hover > a.headerlink,
h5:hover > a.headerlink,
h6:hover > a.headerlink,
dt:hover > a.headerlink,
caption:hover > a.headerlink,
p.caption:hover > a.headerlink,
div.code-block-caption:hover > a.headerlink {
visibility: visible;
}
div.body p.caption {
text-align: inherit;
}
div.body td {
text-align: left;
}
.first {
margin-top: 0 !important;
}
p.rubric {
margin-top: 30px;
font-weight: bold;
}
img.align-left, .figure.align-left, object.align-left {
clear: left;
float: left;
margin-right: 1em;
}
img.align-right, .figure.align-right, object.align-right {
clear: right;
float: right;
margin-left: 1em;
}
img.align-center, .figure.align-center, object.align-center {
display: block;
margin-left: auto;
margin-right: auto;
}
.align-left {
text-align: left;
}
.align-center {
text-align: center;
}
.align-right {
text-align: right;
}
/* -- sidebars -------------------------------------------------------------- */
div.sidebar {
margin: 0 0 0.5em 1em;
border: 1px solid #ddb;
padding: 7px 7px 0 7px;
background-color: #ffe;
width: 40%;
float: right;
}
p.sidebar-title {
font-weight: bold;
}
/* -- topics ---------------------------------------------------------------- */
div.topic {
border: 1px solid #ccc;
padding: 7px 7px 0 7px;
margin: 10px 0 10px 0;
}
p.topic-title {
font-size: 1.1em;
font-weight: bold;
margin-top: 10px;
}
/* -- admonitions ----------------------------------------------------------- */
div.admonition {
margin-top: 10px;
margin-bottom: 10px;
padding: 7px;
}
div.admonition dt {
font-weight: bold;
}
div.admonition dl {
margin-bottom: 0;
}
p.admonition-title {
margin: 0px 10px 5px 0px;
font-weight: bold;
}
div.body p.centered {
text-align: center;
margin-top: 25px;
}
/* -- tables ---------------------------------------------------------------- */
table.docutils {
border: 0;
border-collapse: collapse;
}
table caption span.caption-number {
font-style: italic;
}
table caption span.caption-text {
}
table.docutils td, table.docutils th {
padding: 1px 8px 1px 5px;
border-top: 0;
border-left: 0;
border-right: 0;
border-bottom: 1px solid #aaa;
}
table.footnote td, table.footnote th {
border: 0 !important;
}
th {
text-align: left;
padding-right: 5px;
}
table.citation {
border-left: solid 1px gray;
margin-left: 1px;
}
table.citation td {
border-bottom: none;
}
/* -- figures --------------------------------------------------------------- */
div.figure {
margin: 0.5em;
padding: 0.5em;
}
div.figure p.caption {
padding: 0.3em;
}
div.figure p.caption span.caption-number {
font-style: italic;
}