Skip to content

Commit 8ea3b60

Browse files
uuudownuuudown
committed
add readme
1 parent ea73924 commit 8ea3b60

File tree

2 files changed

+130
-4
lines changed

2 files changed

+130
-4
lines changed

‎README.md

+130-4
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,131 @@
1-
# SV-Sim
2-
IPID:32166, ECCN:EAR99
3-
This includes SV-Sim.
4-
This also includes svsim-qsharp which is the state-vector specially optimized for Q#/QIR.
1+
# SV-Sim: State Vector Quantum Circuit Simulation Environment
2+
3+
A State Vector Quantum Simulation Environment based on PGAS model for single-GPU/CPU, single-node-multi-GPUs/CPUs and multi-nodes GPU/CPU clusters. It supports Intel/AMD/IBM CPUs, NVIDIA/AMD GPUs and Xeon-Phi. It has been tested on OLCF Summit and Spock, ALCF Theta, NERSC Cori, DGX-2 and DGX-A100. Please see our SuperComputing (SC-21) [paper](doc/paper_sc21.pdf) for details.
4+
5+
![alt text](img/structure.png)
6+
7+
## Current version
8+
9+
Latest version: **1.0**
10+
11+
SV-Sim is under active development. Please propose any bugs and suggest any features. We will continuously add new features. Questions and suggestions are welcome.
12+
13+
14+
## About SV-Sim
15+
16+
SV-Sim is a C++/CUDA/HIP implementation for simulating generic quantum circuits through state-vector on single CPU/GPU/Xeon-Phi, single-node-multi-CPUs/GPUs, and multi-node CPU/GPU cluster. As shown in the figure, SV-Sim provides Python/C++ interface. It supports Qiskit, Cirq, Q# as the front-end. It supports OpenQASM and QIR as the intermediate representation. SV-Sim relies on PGAS-based SHMEM model for communication, this includes (1) GPUDirect Peer-to-Peer for single-node multi-GPU (NVIDIA and AMD GPUs) communication; (2) OpenSHMEM for CPU multi-node communication; (3) NVSHMEM (ROC_SHMEM) for GPU multi-node communication. Please see our Supercomputing-21[paper](doc/paper_sc21.pdf) for details.
17+
18+
In addition to the generic SV-Sim, this repository also includes a specialized implementation for Q# [QIR Runtime](https://github.com/microsoft/qsharp-runtime). In this tailored SV-Sim, we realize the multi-controlled gates, exponential gates, and intermediate measurement. We include dozens of applications from the [QDK samples](https://github.com/microsoft/Quantum). The svsim_qir_noise folder includes the density-matrix simulator for Q#/QIR based on the state-vector simulation for noise related simulation. We will discuss it in detail in a future paper.
19+
20+
## Configuration
21+
22+
You may need to update "CMakeLists.txt" for configuration. You need to select the front-end: C++, Python or QIR. You need to select the backend: CPU, NVIDIA GPU or AMD GPU. You need to select the mode: single, OpenMP for single-node multi-devices, or MPI/OpenSHMEM/NVSHMEM for multi-nodes cluster. You may want to enable AVX512 optimization for Xeon-Phi KNL or high-end Intel X86 CPUs. For GPU, you may need to update the compute capability (e.g., 70 for Volta and 80 for Ampere).
23+
24+
We provide a script "set_env.sh" for setting-up the environment on OLCF Summit HPC, and an lsf file for job submission.
25+
26+
## Prerequisite
27+
DM-Sim requires the following packages.
28+
29+
| Dependency | Version | Comments |
30+
|:-----------: | ------- | -------- |
31+
| CUDA | 11.0 or later | For NVIDIA GPU backend |
32+
| GCC | 7.0 or later | |
33+
| OpenMP | 4.0 | For single-node scale-up |
34+
| Spectrum-MPI | 10.3 | For NVIDIA GPU cluster scale-out RDMA|
35+
| NVSHMEM | 2.0.3 | For NVIDIA GPU cluster scale-out |
36+
| Python | 3.4 | For Python-API |
37+
| Pybind11 | 2.5.0 | For Python-API |
38+
| mpi4py | 3.0.3 | For Python-API cluster scale-out |
39+
| ROCM | 3.1.0 | For AMD GPU backend |
40+
41+
The basic CPU version only requires GCC or other standard C++ compiler. It needs CUDA for NVIDIA GPU backend and ROCM for AMD GPU backend. It needs Python and PyBind11 for supporting python interface. It needs OpenSHMEM/NVSHMEM/ROC_SHMEM for CPU/NVIDIA-GPU/AMD-GPU multi-node running.
42+
43+
The Q#/QIR relies on LLVM-10.0 or later, and [Q# Runtime](https://github.com/microsoft/qsharp-runtime).
44+
45+
46+
## Build
47+
48+
```text
49+
cd svsim
50+
mkdir build
51+
cd build
52+
cmake ../
53+
```
54+
55+
## Build
56+
If you use the C++ interface, you will need to develop a C++ driver program and the circuit function. Please see the adder_n10 example under the "example" folder.
57+
58+
```text
59+
./adder_n10_cpu_sin
60+
```
61+
62+
If you use the Python interface, after the library is generated, you can directly execute the python script.
63+
64+
```text
65+
python adder_n10_sin.py 10
66+
```
67+
68+
An example on using the Python interface is given below:
69+
```text
70+
import svsim_py_omp_wrapper as svsim_omp
71+
n_qubits = 10
72+
n_gpus = 4
73+
sim = svsim_omp.Simulation(n_qubits, n_gpus))
74+
sim.append(sim.X(0)) #add an X gate
75+
sim.append(sim.H(1)) #add an H gate
76+
sim.upload() #upload to GPU
77+
sim.run() #run
78+
sim.clear_circuit() #clear existing circuit
79+
sim.append(sim.H(0)) #add a new H gate
80+
sim.upload() #upload to GPU
81+
sim.run() #run new circuit on original states
82+
res = sim.measure(10) #measure with 10 repetitions and return in a list
83+
```
84+
85+
For benchmark applications, please see our [QASMBench](https://arxiv.org/abs/2005.13018) benchmakr suite, which is released [here](https://github.com/pnnl/qasmbench).
86+
87+
## Support Tools
88+
89+
We provide the tool folder for converting OpenQASM code to a python script that can be executed on SV-Sim.
90+
91+
92+
## Authors
93+
94+
#### [Ang Li](http://www.angliphd.com/), Senior Computer Scientist, Pacific Northwest National Laboratory (PNNL)
95+
96+
#### [Sriram Krishnamoorthy](https://hpc.pnl.gov/people/sriram/), Lab Fellow, Pacific Northwest National Laboratory (PNNL)
97+
98+
We are currently collaborating with Bo Fang from PNNL and the Microsoft Quantum team (Chris Granade, Bettina Heim, Stefan Wernli, Robin Kuzmin, Alan Geller, Guen Prawiroatmodjo and Martin Roetteler) on implementing the pipeline from Q# to [QIR](https://devblogs.microsoft.com/qsharp/introducing-quantum-intermediate-representation-qir/) to [SV-Sim](https://github.com/microsoft/qsharp-language/blob/main/Specifications/QIR/List.md). Many thanks to their strong support.
99+
100+
101+
## Citation format
102+
103+
Please cite our SC-21 paper:
104+
- Ang Li and Sriram Krishnamoorthy. "SV-Sim: Scalable PGAS-based State Vector Simulation of Quantum Circuits" In Proceedings of the International Conference for High Performance Computing, Networking, Storage and Analysis, 2021.
105+
106+
Bibtex:
107+
```text
108+
@inproceedings{li2021svsim,
109+
title={SV-Sim: Scalable PGAS-based State Vector Simulation of Quantum Circuits},
110+
author={Li, Ang and Krishnamoorthy, Sriram},
111+
booktitle={Proceedings of the International Conference for High Performance Computing, Networking, Storage and Analysis},
112+
year={2021}
113+
}
114+
```
115+
116+
117+
## License
118+
119+
This project is licensed under the BSD License, see [LICENSE](LICENSE) file for details.
120+
121+
## Acknowledgments
122+
123+
**PNNL-IPID: 32166-E, ECCN: EAR99, IR: PNNL-SA-161181**
124+
125+
This project is fully supported by the [Quantum Science Center (QSC)](https://qscience.org/).The Pacific Northwest National Laboratory (PNNL) is operated by Battelle for the U.S. Department of Energy (DOE) under contract DE-AC05-76RL01830.
126+
127+
## Contributing
128+
129+
Please contact us If you'd like to contribute to SV-Sim. See the contact in our paper or my [webpage](http://www.angliphd.com).
130+
5131

‎img/structure.png

117 KB
Loading

0 commit comments

Comments
 (0)