Skip to content

Commit 1646df9

Browse files
doichanjdoichanj
authored
Add tutorials (#136)
* add tutorial * fix typo * small fixes * refactor directory * add link to tutorial Added a Tutorials section with a link to examples.
1 parent d2ae297 commit 1646df9

7 files changed

Lines changed: 741 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,10 @@ To run the sample example with SQC, you also need to set the library options to
122122
SQC_LIBS="-lsqc_api -lsqc_rpc ... (omitted) ... -pthread"
123123
```
124124

125+
### Tutorials
126+
127+
See [tutorial](tutorials/readme.md) for more examples.
128+
125129
### Making your own interface to Quantum hardware
126130

127131
Qiskit C++ offers an abstract interface to access Quantum hardware. You can make your own interface to the hardware

‎tutorials/circuit.ipynb‎

Lines changed: 240 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,240 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"id": "afafa430-5f99-4d27-93bb-be3751de7dc5",
6+
"metadata": {},
7+
"source": [
8+
"# Making Quantum Circuits\n",
9+
"This tutorial is the first step for Qiskit C++ to make a new quantum circuit.\n",
10+
"\n",
11+
"## Setting for Notebook\n",
12+
"Before starting the tutorial, make sure you already install `Qiskit C-API`, `QRMI` and `xeus-cling` (see readme.md).\n",
13+
"To write C++ application on the notebook, the path to `Qiskit` should be set by using following `#pragma` for `xeus-cling`\n",
14+
"\n",
15+
"It is easy to run this tutorial by putting all components in the same directory level as:\n",
16+
"```\n",
17+
"doichan@doichanT14:/mnt/c/dev/Quantum/qiskit-cpp/tutorial$ ls -l\n",
18+
"total 0\n",
19+
"drwxr-xr-x 1 doichan doichan 4096 Jan 23 17:35 qiskit\n",
20+
"drwxr-xr-x 1 doichan doichan 4096 Jan 23 17:38 qiskit-cpp\n",
21+
"drwxr-xr-x 1 doichan doichan 4096 Jan 22 18:25 qrmi\n",
22+
"doichan@doichanT14:/mnt/c/dev/Quantum/qiskit-cpp/tutorial$\n",
23+
"```"
24+
]
25+
},
26+
{
27+
"cell_type": "code",
28+
"execution_count": 1,
29+
"id": "41f8e2db-7a40-4650-b2b7-76e90990b8a6",
30+
"metadata": {},
31+
"outputs": [],
32+
"source": [
33+
"// setting include path to Qiskit C-API, set your own path here\n",
34+
"#pragma cling add_include_path(\"../../qiskit/dist/c/include\")\n",
35+
"// setting library path to Qiskit C-API, set your own path here\n",
36+
"#pragma cling add_library_path(\"../../qiskit/dist/c/lib\")\n",
37+
"// loading Qiskit\n",
38+
"#pragma cling load(\"qiskit\")\n",
39+
"\n",
40+
"// then set include path for Qiskit C++\n",
41+
"#pragma cling add_include_path(\"../src\")"
42+
]
43+
},
44+
{
45+
"cell_type": "markdown",
46+
"id": "8c47e2bf-361e-4a43-8daf-ff710a33f279",
47+
"metadata": {},
48+
"source": [
49+
"## Make the first Quantum Circuit\n",
50+
"To make a quantum circuit with Qiskit C++, include following header file. "
51+
]
52+
},
53+
{
54+
"cell_type": "code",
55+
"execution_count": 2,
56+
"id": "f712771a-c9aa-4db0-9163-0baa5b5cfc76",
57+
"metadata": {},
58+
"outputs": [],
59+
"source": [
60+
"#include \"circuit/quantumcircuit.hpp\""
61+
]
62+
},
63+
{
64+
"cell_type": "markdown",
65+
"id": "aa3e19b6-85fc-4fff-b295-63895bc8f850",
66+
"metadata": {},
67+
"source": [
68+
"Then you can make a quantum circuit by Qiskit C++. This example will make a quantum circuit with 2 qubits and 2 classical bits."
69+
]
70+
},
71+
{
72+
"cell_type": "code",
73+
"execution_count": 5,
74+
"id": "5dc30268-ebd8-4fa6-a3d4-aef7faef5c98",
75+
"metadata": {},
76+
"outputs": [],
77+
"source": [
78+
"// by using namespace, you can write as similar to Qiskit Python\n",
79+
"using namespace Qiskit::circuit;\n",
80+
"\n",
81+
"// new quantum circuit with 2 qubits and 2 classical bits\n",
82+
"QuantumCircuit circ(2, 2);\n",
83+
"circ.h(0);\n",
84+
"circ.z(1);\n",
85+
"circ.measure(0, 0);\n",
86+
"circ.measure(1, 1);"
87+
]
88+
},
89+
{
90+
"cell_type": "markdown",
91+
"id": "599fadb0-efc8-4409-984a-01cabc6d24b2",
92+
"metadata": {},
93+
"source": [
94+
"You can print out the list of gates on the quantum circuit by `print` function."
95+
]
96+
},
97+
{
98+
"cell_type": "code",
99+
"execution_count": 6,
100+
"id": "5d8d2bf0-c249-4cfa-a86d-4cf8558a1a5f",
101+
"metadata": {},
102+
"outputs": [
103+
{
104+
"name": "stdout",
105+
"output_type": "stream",
106+
"text": [
107+
"h(0) \n",
108+
"z(1) \n",
109+
"measure(0) (0) \n",
110+
"measure(1) (1) \n"
111+
]
112+
}
113+
],
114+
"source": [
115+
"circ.print();"
116+
]
117+
},
118+
{
119+
"cell_type": "markdown",
120+
"id": "ff76952a-081f-440c-a5a9-24c4ecda7e7d",
121+
"metadata": {},
122+
"source": [
123+
"## Using Registers\n",
124+
"`QuantumRegister` and `ClassicalRegister` classes are used to name the registers. The qubits and classical bits can be grouped into some register classes and can be used to identify instead of using global bits numbers. It is usefull for grouping classical bits for measurements.\n",
125+
"\n",
126+
"This example makes a quantum circuit from `QuantumRegister` and `ClassicalRegister` classes."
127+
]
128+
},
129+
{
130+
"cell_type": "code",
131+
"execution_count": 8,
132+
"id": "12b8b710-792c-4359-afaa-09b360689b51",
133+
"metadata": {},
134+
"outputs": [
135+
{
136+
"name": "stdout",
137+
"output_type": "stream",
138+
"text": [
139+
"measure(0) (2) \n",
140+
"measure(1) (3) \n",
141+
"h(0) \n",
142+
"x(1) \n",
143+
"measure(0) (0) \n",
144+
"measure(1) (1) \n"
145+
]
146+
}
147+
],
148+
"source": [
149+
"using namespace Qiskit::circuit;\n",
150+
"\n",
151+
"// new quantum register with 2 qubits\n",
152+
"auto qreg = QuantumRegister(2);\n",
153+
"// new classical register with 2 bits named as measure\n",
154+
"auto creg = ClassicalRegister(2, std::string(\"measure\"));\n",
155+
"// new classical register with 2 bits named as test\n",
156+
"auto ctest = ClassicalRegister(2, std::string(\"test\"));\n",
157+
"// make a new quantum circuit with registers\n",
158+
"QuantumCircuit circ_with_reg(std::vector<QuantumRegister>({qreg,}), std::vector<ClassicalRegister>({creg, ctest}));\n",
159+
"\n",
160+
"circ_with_reg.measure(qreg, ctest);\n",
161+
"circ_with_reg.h(qreg[0]);\n",
162+
"circ_with_reg.x(qreg[1]);\n",
163+
"circ_with_reg.measure(qreg, creg);\n",
164+
"\n",
165+
"circ_with_reg.print();"
166+
]
167+
},
168+
{
169+
"cell_type": "markdown",
170+
"id": "76b04d75-fa03-4e9b-b1fa-86aa135b48ef",
171+
"metadata": {},
172+
"source": [
173+
"Also you can print out the quantum circuit as QASM3 format."
174+
]
175+
},
176+
{
177+
"cell_type": "code",
178+
"execution_count": 9,
179+
"id": "28fcc7ad-a2e1-468b-b412-0ce7361c2bc8",
180+
"metadata": {},
181+
"outputs": [
182+
{
183+
"name": "stdout",
184+
"output_type": "stream",
185+
"text": [
186+
"OPENQASM 3.0;\n",
187+
"include \"stdgates.inc\";\n",
188+
"qubit[2] q;\n",
189+
"bit[2] measure;\n",
190+
"bit[2] test;\n",
191+
"test[0] = measure q[0];\n",
192+
"test[1] = measure q[1];\n",
193+
"h q[0];\n",
194+
"x q[1];\n",
195+
"measure[0] = measure q[0];\n",
196+
"measure[1] = measure q[1];\n",
197+
"\n"
198+
]
199+
}
200+
],
201+
"source": [
202+
"std::cout << circ_with_reg.to_qasm3() << std::endl;"
203+
]
204+
},
205+
{
206+
"cell_type": "markdown",
207+
"id": "225680c9-721e-4bd4-8b5b-bf4f5b78d799",
208+
"metadata": {},
209+
"source": [
210+
"***\n",
211+
"Next tutorial : \n",
212+
"[Running Quantum Circuits with Qiskit C++](run_circuits.ipynb)"
213+
]
214+
},
215+
{
216+
"cell_type": "code",
217+
"execution_count": null,
218+
"id": "f6ded246-8801-465e-8033-a10de2543adc",
219+
"metadata": {},
220+
"outputs": [],
221+
"source": []
222+
}
223+
],
224+
"metadata": {
225+
"kernelspec": {
226+
"display_name": "C++11",
227+
"language": "C++11",
228+
"name": "xcpp11"
229+
},
230+
"language_info": {
231+
"codemirror_mode": "text/x-c++src",
232+
"file_extension": ".cpp",
233+
"mimetype": "text/x-c++src",
234+
"name": "c++",
235+
"version": "11"
236+
}
237+
},
238+
"nbformat": 4,
239+
"nbformat_minor": 5
240+
}

‎tutorials/hgz_on_iqp.png‎

91 KB
Loading

‎tutorials/python_vs_cpp.png‎

196 KB
Loading

‎tutorials/qiskit-cpp-structure.png‎

157 KB
Loading

‎tutorials/readme.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# Qiskit C++ Tutorial
2+
3+
## Qiskit C++ Overview
4+
Qiskit C++ is an opensource interface library for Quantum Centric Super Computing applications.
5+
Qiskit C++ provides similar interface classes to Python interface of Qiskit through Qiskit C-API, can be used from C++ applications.
6+
You do not have to bind your applications to Python to make and run the quantum circuits.
7+
Qiskit C++ is easy to use library, consists of header files only, so you do not have to build any binaries and install to the system, but you only have to include Qiskit C++ header files from your applicaitons.
8+
9+
10+
Qiskit C++ supports:
11+
12+
- Building quantum circuits using standard gates
13+
- Transpiling quantum circuits to ISA circuits for a target quantum hardware
14+
- Running quantum circuits through sampler interface on a quantum hardware
15+
16+
17+
![alt text](python_vs_cpp.png)
18+
This example shows building GHZ circuit in Qiskit (Python) and Qiksit C++.
19+
As you can see, only the difference between Python and C++ is type definitions and end of line semicorons in C++.
20+
Most of classes and functions implemented in Qiskit C++ are as same as that of Qiskit Python.
21+
So it is easy to port Qiskit codes into your C++ applications using Qiskit C++.
22+
23+
24+
![alt C-API and Qiskit C++ interface structure](qiskit-cpp-structure.png)
25+
This chart shows how Qiskit C++ is implemented by using Qiskit C-API. Qiskit C++ accesses Qiskit's core functions written in Rust through C-API.
26+
To access quantum resources, we use one of `QRMI` https://github.com/qiskit-community/qrmi, `Qiskit IBM Runtime C` https://github.com/Qiskit/qiskit-ibm-runtime-c
27+
or `SQC` https://github.com/jhpc-quantum/SQC (for `ibm_kobe`) through runtime class of Qiskit C++.
28+
29+
## Getting started
30+
31+
Before coding with Qiskit C++, install dependencies.
32+
33+
### Bulding Qiskit C-API Library
34+
35+
```
36+
git clone git@github.com:Qiskit/qiskit.git
37+
cd qiskit
38+
make c
39+
```
40+
To build Qiskit C-API library, you will need Rust compiler.
41+
See also https://github.com/Qiskit/qiskit/tree/main/crates/cext
42+
43+
Make sure you will need the path to the Qiskit later to include and link from Qiskit C++.
44+
45+
### Building Runtime Service Interface Library
46+
47+
To access quantum hardware from Qiskit C++, install one of the runtime service API.
48+
This example installs `QRMI` as a runtiem service API.
49+
50+
```
51+
git clone git@github.com:qiskit-community/qrmi.git
52+
cd qrmi
53+
cargo build --release
54+
```
55+
Make sure you will need the path to the QRMI later to include and link from Qiskit C++.
56+
57+
### Other Software
58+
59+
Qiskit C++ uses nlohmann_json https://github.com/nlohmann/json to read/write JSON format.
60+
Install and set include path so that Qiskit C++ can find it.
61+
62+
### Building Sample of Qiskit C++
63+
64+
Now you can use Qiskit C++ from the applications. This example builds examples of Qiskit C++.
65+
66+
```
67+
cd samples
68+
mkdir build
69+
cd build
70+
cmake -DQISKIT_ROOT=(put a path to the root of Qiskit you cloned) -DQRMI_ROOT=(put a path to the root of QRMI you cloned) ..
71+
make
72+
```
73+
Set `QISKIT_ROOT` and `QRMI_ROOT` to cmake to set include path and library path referred from Qiskit C++.
74+
75+
In your applications, set include path and library path to compiler options:
76+
```
77+
-I${QISKIT_ROOT}/dist/c/include -I${QRMI}/
78+
-L${QISKIT_ROOT}/dist/c/lib -L${QRMI}/target/Release
79+
```
80+
81+
See [CMakeLists.txt](../samples/CMakeLists.txt) in samples.
82+
83+
## Getting Ready for Qiskit C++ Tutorial
84+
85+
Qiskit C++ tutorial uses Jupyter notebook to learn interactively. Before go into the tutorial, install Qiskit C-API and QRMI shown above, and install `xeus-cling` https://github.com/jupyter-xeus/xeus-cling to run C++ code interactively on Jupyter notebook.
86+
87+
***
88+
## Tutorials
89+
90+
1. [Making Quantum Circuits](circuit.ipynb)
91+
2. [Runnning Quantum Circuits](run_circuit.ipynb)
92+
93+

0 commit comments

Comments
 (0)