README.md 5.46 KB
Newer Older
Mccaskey, Alex's avatar
Mccaskey, Alex committed
1
![XACC](docs/assets/xacc_full_logo.svg)
Mccaskey, Alex's avatar
Mccaskey, Alex committed
2

3
4
5
|  master | xacc-devel |
|:-------|:-------|
|[![pipeline status](https://code.ornl.gov/qci/xacc/badges/master/pipeline.svg)](https://code.ornl.gov/qci/xacc/commits/master) | [![pipeline status](https://code.ornl.gov/qci/xacc/badges/xacc-devel/pipeline.svg)](https://code.ornl.gov/qci/xacc/commits/xacc-devel) |
Mccaskey, Alex's avatar
Mccaskey, Alex committed
6

Mccaskey, Alex's avatar
Mccaskey, Alex committed
7
## Language and Hardware Independent Quantum Programming Framework
8
9
10
11
XACC is an extensible compilation framework for hybrid quantum-classical computing architectures.
It provides extensible language frontend and hardware backend compilation components glued together
via a novel quantum intermediate representation. XACC currently supports quantum-classical programming
and enables the execution of quantum kernels on IBM, Rigetti, and D-Wave QPUs, as well as a number
Mccaskey, Alex's avatar
Mccaskey, Alex committed
12
of quantum computer simulators.
Mccaskey, Alex's avatar
Mccaskey, Alex committed
13

Mccaskey, Alex's avatar
Mccaskey, Alex committed
14
15
16
Documentation
-------------

17
18
* [Website and Documentation](https://xacc.readthedocs.io)
* [API Documentation](https://ornl-qci.github.io/xacc-api-docs/)
Mccaskey, Alex's avatar
Mccaskey, Alex committed
19

Mccaskey, Alex's avatar
Mccaskey, Alex committed
20
21
Quick Start
-----------
Mccaskey, Alex's avatar
Mccaskey, Alex committed
22
Click [![Gitpod Ready-to-Code](https://img.shields.io/badge/Gitpod-Ready--to--Code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/eclipse/xacc) 
23
to open up a pre-configured Eclipse Theia IDE. You should immediately be able to 
Mccaskey, Alex's avatar
Mccaskey, Alex committed
24
run any of the C++ or Python examples from the included terminal:
Mccaskey, Alex's avatar
Mccaskey, Alex committed
25
```bash
Mccaskey, Alex's avatar
Mccaskey, Alex committed
26
27
[example C++ executables are in build/quantum/examples/*]
$ build/quantum/examples/qasm/deuteron_from_qasm
Mccaskey, Alex's avatar
Mccaskey, Alex committed
28

Mccaskey, Alex's avatar
Mccaskey, Alex committed
29
30
[example Python scripts are in python/examples/*]
$ python3 python/examples/deuteronH2.py
31
32
33

[run some XACC benchmarks]
$ python3 -m xacc --benchmark python/benchmark/chemistry/benchmarks/tnqvm_nah_ucc1.ini 
Mccaskey, Alex's avatar
Mccaskey, Alex committed
34
```
35
36
37
38
All code is here and you can quickly start developing. We recommend 
turning on file auto-save by clicking ``File > Auto Save ``.
Note the Gitpod free account provides 100 hours of use for the month, so if 
you foresee needing more time, we recommend our nightly docker images.
Mccaskey, Alex's avatar
Mccaskey, Alex committed
39

40
The XACC nightly docker images also serve an Eclipse Theia IDE (the same IDE Gitpod uses) on port 3000. To get started, run 
Mccaskey, Alex's avatar
Mccaskey, Alex committed
41
42
43
```bash
$ docker run --security-opt seccomp=unconfined --init -it -p 3000:3000 xacc/xacc
```
44
45
Navigate to ``https://localhost:3000`` in your browser to open the IDE and get started with XACC. These are deployed 
nightly, with ``xacc-tnqvm-exatn`` (tensor network simulator) and ``xacc-quac`` (pulse-level simulation) variants.
Mccaskey, Alex's avatar
Mccaskey, Alex committed
46
47


Mccaskey, Alex's avatar
Mccaskey, Alex committed
48
49
Build from Source
-----------------
50
51
Full installation details can be followed [here](https://xacc.readthedocs.io/en/latest/install.html).

52
Ensure that you have installed CMake 3.12+, a C++17 compliant compiler (GCC 8+, Clang 5+), and
53
54
CURL development headers and libraries with OpenSSL support
(see [prerequisites](http://xacc.readthedocs.io/en/latest/install.html#pre-requisites)).
Mccaskey, Alex's avatar
Mccaskey, Alex committed
55

56
It is also recommended (though optional) that you install BLAS and LAPACK development libraries (for various simulators),
Mccaskey, Alex's avatar
Mccaskey, Alex committed
57
Python 3 development headers (for the Python API), and Libunwind (for stack trace printing).
Mccaskey, Alex's avatar
Mccaskey, Alex committed
58

59
To enable XACC Python support, ensure that `python3` is set to your desired version of Python 3. CMake will
60
61
62
find the corresponding development headers. Ensure that when you try to run XACC-enabled Python scripts
you are using the same `python3` executable that was set during your build.

Mccaskey, Alex's avatar
Mccaskey, Alex committed
63
64
65
On Mac OS X, we recommend our users install GCC 8 via Homebrew instead of relying
on XCode command line tools installation and the default Apple Clang compilers.
See [here](https://xacc.readthedocs.io/en/latest/install.html#mac-os-x) for more details on this.
Mccaskey, Alex's avatar
Mccaskey, Alex committed
66

Mccaskey, Alex's avatar
Mccaskey, Alex committed
67
Clone the repository recursively, configure with `cmake` and build with `make`
Mccaskey, Alex's avatar
Mccaskey, Alex committed
68
```bash
Mccaskey, Alex's avatar
Mccaskey, Alex committed
69
$ git clone https://github.com/eclipse/xacc
Mccaskey, Alex's avatar
Mccaskey, Alex committed
70
$ cd xacc && mkdir build && cd build
Mccaskey, Alex's avatar
Mccaskey, Alex committed
71
[default cmake call]
72
$ cmake ..
Mccaskey, Alex's avatar
Mccaskey, Alex committed
73
[with tests and examples]
74
$ cmake .. -DXACC_BUILD_EXAMPLES=TRUE -DXACC_BUILD_TESTS=TRUE
Mccaskey, Alex's avatar
Mccaskey, Alex committed
75
[now build xacc]
76
$ make install
Mccaskey, Alex's avatar
Mccaskey, Alex committed
77
78
79
80
81
82
[for a speedier build on linux]
$ make -j$(nproc --all) install
[and on mac os x]
$ make -j$(sysctl -n hw.physicalcpu) install
[if built with tests, run them]
$ ctest --output-on-failure
Mccaskey, Alex's avatar
Mccaskey, Alex committed
83
```
84
See full documentation for all CMake optional arguments.
85
86
87

Your installation will be in `$HOME/.xacc`. If you built with the Python API,
be sure to update your `PYTHONPATH` environment variable to point to the installation:
Mccaskey, Alex's avatar
Mccaskey, Alex committed
88
89
```bash
$ export PYTHONPATH=$PYTHONPATH:$HOME/.xacc
90
```
Mccaskey, Alex's avatar
Mccaskey, Alex committed
91

Mccaskey, Alex's avatar
Mccaskey, Alex committed
92
93
94
95
96
97
98
99
You will probably want the XACC default simulator, TNQVM. To install, run the following:
```bash
$ git clone https://github.com/ornl-qci/tnqvm
$ cd tnqvm && mkdir build && cd build
$ cmake .. -DXACC_DIR=~/.xacc
$ make install
```

Mccaskey, Alex's avatar
Mccaskey, Alex committed
100
101
102
103
104
105
106
107
108
109
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 with the bug tag. You can ask
questions by creating a new issue with the question tag.

License
-------

Mccaskey, Alex's avatar
Mccaskey, Alex committed
110
XACC is dual licensed - [Eclipse Public License](LICENSE.EPL) and [Eclipse Distribution License](LICENSE.EDL).
Mccaskey, Alex's avatar
Mccaskey, Alex committed
111
112
113
114
115

Cite XACC
----------
If you use XACC in your research, please use the following citation
```
116
117
118
119
120
121
122
123
124
125
126
127
@article{xacc_2020,
	doi = {10.1088/2058-9565/ab6bf6},
	url = {https://doi.org/10.1088%2F2058-9565%2Fab6bf6},
	year = 2020,
	month = {feb},
	publisher = {{IOP} Publishing},
	volume = {5},
	number = {2},
	pages = {024002},
	author = {Alexander J McCaskey and Dmitry I Lyakh and Eugene F Dumitrescu and Sarah S Powers and Travis S Humble},
	title = {{XACC}: a system-level software infrastructure for heterogeneous quantum{\textendash}classical computing},
	journal = {Quantum Science and Technology}
Mccaskey, Alex's avatar
Mccaskey, Alex committed
128
129
}
```