Add tutorials

README.md

@@ -122,6 +122,10 @@ To run the sample example with SQC, you also need to set the library options to
 SQC_LIBS="-lsqc_api -lsqc_rpc ... (omitted) ... -pthread"
 ```
 
+### Tutorials
+
+See [tutorial](tutorials/readme.md) for more examples.
+
 ### Making your own interface to Quantum hardware
 
 Qiskit C++ offers an abstract interface to access Quantum hardware. You can make your own interface to the hardware

tutorials/circuit.ipynb

@@ -0,0 +1,240 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "afafa430-5f99-4d27-93bb-be3751de7dc5",
+   "metadata": {},
+   "source": [
+    "# Making Quantum Circuits\n",
+    "This tutorial is the first step for Qiskit C++ to make a new quantum circuit.\n",
+    "\n",
+    "## Setting for Notebook\n",
+    "Before starting the tutorial, make sure you already install `Qiskit C-API`, `QRMI` and `xeus-cling` (see readme.md).\n",
+    "To write C++ application on the notebook, the path to `Qiskit` should be set by using following `#pragma` for `xeus-cling`\n",
+    "\n",
+    "It is easy to run this tutorial by putting all components in the same directory level as:\n",
+    "```\n",
+    "doichan@doichanT14:/mnt/c/dev/Quantum/qiskit-cpp/tutorial$ ls -l\n",
+    "total 0\n",
+    "drwxr-xr-x 1 doichan doichan 4096 Jan 23 17:35 qiskit\n",
+    "drwxr-xr-x 1 doichan doichan 4096 Jan 23 17:38 qiskit-cpp\n",
+    "drwxr-xr-x 1 doichan doichan 4096 Jan 22 18:25 qrmi\n",
+    "doichan@doichanT14:/mnt/c/dev/Quantum/qiskit-cpp/tutorial$\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "41f8e2db-7a40-4650-b2b7-76e90990b8a6",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "// setting include path to Qiskit C-API, set your own path here\n",
+    "#pragma cling add_include_path(\"../../qiskit/dist/c/include\")\n",
+    "// setting library path to Qiskit C-API, set your own path here\n",
+    "#pragma cling add_library_path(\"../../qiskit/dist/c/lib\")\n",
+    "// loading Qiskit\n",
+    "#pragma cling load(\"qiskit\")\n",
+    "\n",
+    "// then set include path for Qiskit C++\n",
+    "#pragma cling add_include_path(\"../src\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8c47e2bf-361e-4a43-8daf-ff710a33f279",
+   "metadata": {},
+   "source": [
+    "## Make the first Quantum Circuit\n",
+    "To make a quantum circuit with Qiskit C++, include following header file. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "f712771a-c9aa-4db0-9163-0baa5b5cfc76",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#include \"circuit/quantumcircuit.hpp\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "aa3e19b6-85fc-4fff-b295-63895bc8f850",
+   "metadata": {},
+   "source": [
+    "Then you can make a quantum circuit by Qiskit C++. This example will make a quantum circuit with 2 qubits and 2 classical bits."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "5dc30268-ebd8-4fa6-a3d4-aef7faef5c98",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "// by using namespace, you can write as similar to Qiskit Python\n",
+    "using namespace Qiskit::circuit;\n",
+    "\n",
+    "// new quantum circuit with 2 qubits and 2 classical bits\n",
+    "QuantumCircuit circ(2, 2);\n",
+    "circ.h(0);\n",
+    "circ.z(1);\n",
+    "circ.measure(0, 0);\n",
+    "circ.measure(1, 1);"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "599fadb0-efc8-4409-984a-01cabc6d24b2",
+   "metadata": {},
+   "source": [
+    "You can print out the list of gates on the quantum circuit by `print` function."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "id": "5d8d2bf0-c249-4cfa-a86d-4cf8558a1a5f",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "h(0) \n",
+      "z(1) \n",
+      "measure(0) (0) \n",
+      "measure(1) (1) \n"
+     ]
+    }
+   ],
+   "source": [
+    "circ.print();"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ff76952a-081f-440c-a5a9-24c4ecda7e7d",
+   "metadata": {},
+   "source": [
+    "## Using Registers\n",
+    "`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",
+    "\n",
+    "This example makes a quantum circuit from `QuantumRegister` and `ClassicalRegister` classes."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "id": "12b8b710-792c-4359-afaa-09b360689b51",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "measure(0) (2) \n",
+      "measure(1) (3) \n",
+      "h(0) \n",
+      "x(1) \n",
+      "measure(0) (0) \n",
+      "measure(1) (1) \n"
+     ]
+    }
+   ],
+   "source": [
+    "using namespace Qiskit::circuit;\n",
+    "\n",
+    "// new quantum register with 2 qubits\n",
+    "auto qreg = QuantumRegister(2);\n",
+    "// new classical register with 2 bits named as measure\n",
+    "auto creg = ClassicalRegister(2, std::string(\"measure\"));\n",
+    "// new classical register with 2 bits named as test\n",
+    "auto ctest = ClassicalRegister(2, std::string(\"test\"));\n",
+    "// make a new quantum circuit with registers\n",
+    "QuantumCircuit circ_with_reg(std::vector<QuantumRegister>({qreg,}), std::vector<ClassicalRegister>({creg, ctest}));\n",
+    "\n",
+    "circ_with_reg.measure(qreg, ctest);\n",
+    "circ_with_reg.h(qreg[0]);\n",
+    "circ_with_reg.x(qreg[1]);\n",
+    "circ_with_reg.measure(qreg, creg);\n",
+    "\n",
+    "circ_with_reg.print();"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "76b04d75-fa03-4e9b-b1fa-86aa135b48ef",
+   "metadata": {},
+   "source": [
+    "Also you can print out the quantum circuit as QASM3 format."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "id": "28fcc7ad-a2e1-468b-b412-0ce7361c2bc8",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "OPENQASM 3.0;\n",
+      "include \"stdgates.inc\";\n",
+      "qubit[2] q;\n",
+      "bit[2] measure;\n",
+      "bit[2] test;\n",
+      "test[0] = measure q[0];\n",
+      "test[1] = measure q[1];\n",
+      "h q[0];\n",
+      "x q[1];\n",
+      "measure[0] = measure q[0];\n",
+      "measure[1] = measure q[1];\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "std::cout << circ_with_reg.to_qasm3() << std::endl;"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "225680c9-721e-4bd4-8b5b-bf4f5b78d799",
+   "metadata": {},
+   "source": [
+    "***\n",
+    "Next tutorial : \n",
+    "[Running Quantum Circuits with Qiskit C++](run_circuits.ipynb)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f6ded246-8801-465e-8033-a10de2543adc",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "C++11",
+   "language": "C++11",
+   "name": "xcpp11"
+  },
+  "language_info": {
+   "codemirror_mode": "text/x-c++src",
+   "file_extension": ".cpp",
+   "mimetype": "text/x-c++src",
+   "name": "c++",
+   "version": "11"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

tutorials/readme.md

@@ -0,0 +1,93 @@
+# Qiskit C++ Tutorial
+
+## Qiskit C++ Overview
+Qiskit C++ is an opensource interface library for Quantum Centric Super Computing applications.
+Qiskit C++ provides similar interface classes to Python interface of Qiskit through Qiskit C-API, can be used from C++ applications.
+You do not have to bind your applications to Python to make and run the quantum circuits.
+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.
+
+
+Qiskit C++ supports:
+
+- Building quantum circuits using standard gates
+- Transpiling quantum circuits to ISA circuits for a target quantum hardware
+- Running quantum circuits through sampler interface on a quantum hardware
+
+
+![alt text](python_vs_cpp.png)
+This example shows building GHZ circuit in Qiskit (Python) and Qiksit C++.
+As you can see, only the difference between Python and C++ is type definitions and end of line semicorons in C++.
+Most of classes and functions implemented in Qiskit C++ are as same as that of Qiskit Python.
+So it is easy to port Qiskit codes into your C++ applications using Qiskit C++.
+
+
+![alt C-API and Qiskit C++ interface structure](qiskit-cpp-structure.png)
+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.
+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
+ or `SQC` https://github.com/jhpc-quantum/SQC (for `ibm_kobe`) through runtime class of Qiskit C++.
+
+## Getting started
+
+Before coding with Qiskit C++, install dependencies.
+
+### Bulding Qiskit C-API Library
+
+```
+git clone git@github.com:Qiskit/qiskit.git
+cd qiskit
+make c
+```
+To build Qiskit C-API library, you will need Rust compiler.
+See also https://github.com/Qiskit/qiskit/tree/main/crates/cext
+
+Make sure you will need the path to the Qiskit later to include and link from Qiskit C++.
+
+### Building Runtime Service Interface Library
+
+To access quantum hardware from Qiskit C++, install one of the runtime service API.
+This example installs `QRMI` as a runtiem service API.
+
+```
+git clone git@github.com:qiskit-community/qrmi.git
+cd qrmi
+cargo build --release
+```
+Make sure you will need the path to the QRMI later to include and link from Qiskit C++.
+
+### Other Software
+
+Qiskit C++ uses nlohmann_json https://github.com/nlohmann/json to read/write JSON format.
+Install and set include path so that Qiskit C++ can find it.
+
+### Building Sample of Qiskit C++
+
+Now you can use Qiskit C++ from the applications. This example builds examples of Qiskit C++.
+
+```
+cd samples
+mkdir build
+cd build
+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) ..
+make
+```
+Set `QISKIT_ROOT` and `QRMI_ROOT` to cmake to set include path and library path referred from Qiskit C++.
+
+In your applications, set include path and library path to compiler options:
+```
+-I${QISKIT_ROOT}/dist/c/include -I${QRMI}/
+-L${QISKIT_ROOT}/dist/c/lib -L${QRMI}/target/Release
+```
+
+See [CMakeLists.txt](../samples/CMakeLists.txt) in samples.
+
+## Getting Ready for Qiskit C++ Tutorial
+
+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.
+
+***
+## Tutorials
+
+1. [Making Quantum Circuits](circuit.ipynb)
+2. [Runnning Quantum Circuits](run_circuit.ipynb)
+
+