QPI: A Holo visualization of the QSphere to help Quantum Programing with Qiskit learning

QPi is an implementation of the Qiskit platform meant to facilitate learning by visualizing the Qsphere from different views. With QPi you can:

• Visualise QSphere in 3 dimentions (with four views)
• Run any Qiskit textbook and see the resulting Qsphere in 3 dimentions (with 4 views)
• Wifi Access point to allow you to use it in unknown territory (without internet connection)

You can see examples of the Qsphere visualization in the Introduction to QPi notebook, or watch the demo video and the assembly video

You can download the ready to use disk image

QPi is an implementation of the Qiskit platform meant to facilitate learning by visualizing the Qsphere from different views, If you want to know a little more about the history of the project, please check the publication

Get Started

You can get QPi in two different ways:

• Follow the tutorial to install it yourself.
• Download the ready to use disk image and write it in the SD

To build a QPi you will need:

• Raspberry Pi 4
• Power Supply for the Raspberry Pi
• Micro SD card with at least 8GB of storage (We recommend 16 GB)
• 5 inch screen (or bigger) Like This one
• Ready to use holo pyramid (or you can build your own) Like This one
• [Optional] Raspberry Pi Battery Hat : in case you want to use the QPi anywhere without the need to connect it to a power source
• ✨Magic ✨

Installation Tutorial

In this tutorial we will

• Install and configure the Raspberry Pi Operating System and Python
• Install Jupyter Hub
• Install Qiskit and feh
• Set up JupyterHub as a system service
• Create the auto start script
• Installing and running QPi

This tutorial has been created and tested on the following versions:

• Operating System : Raspbian GNU/Linux 10 (buster)
• Python 3.7.3
• Qiskit 0.26.2

This tutorial is inspired, and uses knowledge from:

• RasQberry: Quantum Computing is the Coolest Project for Raspberry
• Setup your home JupyterHub on a Raspberry Pi
• Install Qiskit

Install Raspberry Pi OS

1. Download Raspberry pi Imager, Install Raspberry OS, and access it via ssh. More information can be found here:

   -Getting Started

   -SSH

   -Set Up a Headless Raspberry Pi

2. Connect using SSH to RPi and Update the OS. This is the standard procedure to make sure that you are up to date

   sudo apt update && sudo apt -y upgrade && sudo apt -y dist-upgrade

3. Create a swap space of 1 GB.

   As some of the compilation and installation tasks require more than the 512 MB of RAM that are available on smaller Raspberry Pi models, we increase the swap space to 1 GB. The size of the configured swap space can be checked with free -m.

   pi@qpi:~ $ sudo sed -i 's/CONF_SWAPSIZE=100/CONF_SWAPSIZE=1024/' /etc/dphys-swapfile
   pi@qpi:~ $ sudo /etc/init.d/dphys-swapfile stop
   pi@qpi:~ $ sudo /etc/init.d/dphys-swapfile start

4. Optional Installing and configuring the screen

   Some screens have very specific resolution and features (like touch screen, controlling the brightness etc.) and need to have specific drivers to enable those features. Please refer to the tutorial related to your screen manufacturer. In our case we are using a 5-inch HDMI capacitive screen.

   pi@qpi:~ $ git clone https://github.com/goodtft/LCD-show.git
   pi@qpi:~ $ cd LCD-show/
   pi@qpi:~ $ sudo ./LCD5-show

5. Disable the screen saver

   When using the QPi usually we interact with it remotely using the Jupyter Notebook and feh to display the QSphere. As a result, after a certain time of using the QPi, the screen may go dark or start using the screensaver. To avoid that, we recommend disabling the screensaver and screen blanking.

   Please find here different ways to disable the screensaver

6. Configure the RPI to use Python 3

   Qiskit supports Python 3.7 or later

   pi@qpi:~ $ sudo rm /usr/bin/python 
   pi@qpi:~ $ sudo ln -s /usr/bin/python3 /usr/bin/python

7. Install and upgrade the python package manager pip

   Pip is the package installer / manager for Python. We will need to install and update needed software like : notebook, jupyterHub, setuptools-rust, pyscf, cython ect. You can identify all the dependencies that pip support us to install by searching "pip3 install" in this tutorial.

   pi@qpi:~ $ sudo apt-get install python3-pip 
   pi@qpi:~ $ sudo pip3 install --upgrade pip
   

Install Jupyter Hub

1. Install Node JS and the Proxy

   To be able to run Jupyter hub, we need a proxy that routes the user requests to the hub and the notebook servers. In this tutorial, we will use configurable-http-proxy that run on NodeJS

   pi@qpi:~ $ sudo su
   root@qpi:/home/pi# curl -fsSL https://deb.nodesource.com/setup_14.x | bash -
   root@qpi:/home/pi# apt-get install -y nodejs
   root@qpi:/home/pi# sudo npm install -g configurable-http-proxy

   go back to pi user

   root@qpi:/home/pi# exit
   pi@qpi:~ $

2. Install Jupyter Notebook and JupyterHub

   In the QPi project, we use the main screen of the device to display a projection of a QSphere. As a result, the only way to interact with the QPi (a part of having a second screen) will be remotely. Since Qiskit is based on python, and most of it is tutorials uses Jupyter notebook, we wanted this project to have a familiar interface and allow anyone to easily start experimenting with Quantum computing and Qiskit. Having this set of tools will allow the user to access a jupyter notebook in his personal device (laptop/smartphone), create a circuit and watch the QPi display it as a hologram.

   pi@qpi:~ $ sudo -H pip3 install notebook jupyterhub

   Generate Jupyterhub Config and move it to root folder

   pi@qpi:~ $ jupyterhub --generate-config 

   Writing default config to: jupyterhub_config.py

   pi@qpi:~ $ sudo mv jupyterhub_config.py /root

   Creating Qpi folder

   pi@qpi:~ $ mkdir qpi
   pi@qpi:~ $ cd qpi/

Install Qiskit and feh

The main idea of the QPi project is to be abe to use your personal device to connect to the QPi. Open a Jupyter notebook remotely, and allow the user to create any Quantum circuit and visualize its QSphere as a hologram projection. To be able to do that, we have created a python library that when used will create an image composed by four different views of the Qsphere and save it with a specific name in a specific folder. We then use feh a lightweight image viewer to display this image with a specified refresh rate (in this tutorial we use one second). To have a good user experience, we recommend running feh at startup.

1. Manual installation of some dependencies for Qiskit

   pi@qpi:~ $ sudo -H pip install setuptools-rust
   pi@qpi:~ $ curl -o get_rustup.sh -s https://sh.rustup.rs
   pi@qpi:~ $ sudo sh ./get_rustup.sh -y
   pi@qpi:~ $ sudo -H pip install --prefer-binary retworkx
   pi@qpi:~ $ sudo -H pip install --prefer-binary cvxpy

   Installing libcint, pyscf and cython

   pi@qpi:~ $ sudo apt -y install cmake libatlas-base-dev git feh unclutter
   pi@qpi:~/qpi $ git clone https://github.com/sunqm/libcint.git
   pi@qpi:~/qpi $ mkdir -p libcint/build && cd libcint/build
   pi@qpi:~/qpi/libcint/build $ cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr/local/ ..
   pi@qpi:~/qpi/libcint/build $ sudo make install
   pi@qpi:~/qpi/libcint/build $ sudo -H pip install --prefer-binary pyscf cython

2. Installation of the latest versions of Qiskit elements

   pi@qpi:~/qpi/libcint/build $ sudo -H pip install --prefer-binary six
   pi@qpi:~/qpi/libcint/build $ sudo -H pip install --prefer-binary 'qiskit[visualization]'

   Verify qiskit installation

   pi@qpi:~/qpi/libcint/build $ pip list | grep qiskit

   You should get something like that (version may vary)

   qiskit               0.26.2
   qiskit-aer           0.8.2
   qiskit-aqua          0.9.1
   qiskit-ibmq-provider 0.13.1
   qiskit-ignis         0.6.0
   qiskit-terra         0.17.4

3. Set up JupyterHub as a system service

   Setting up JupyterHub as a service will allow us to start it automatically

   pi@qpi:~/qpi/libcint/build $ sudo nano /lib/systemd/system/jupyterhub.service

   and paste the following configuration

   [Unit]
   Description=JupyterHub Service
   After=multi-user.target
   [Service]
   User=root
   ExecStart=/usr/local/bin/jupyterhub --config=/root/jupyterhub_config.py
   Restart=on-failure
   [Install]
   WantedBy=multi-user.target

   Type ctrl + x, then Y and enter to save the file and exit

   pi@qpi:~/qpi/libcint/build $ sudo systemctl daemon-reload
   pi@qpi:~/qpi/libcint/build $ sudo systemctl start jupyterhub
   pi@qpi:~/qpi/libcint/build $ sudo systemctl enable jupyterhub 
   Created symlink /etc/systemd/system/multi-user.target.wants/jupyterhub.service → /lib/systemd/system/jupyterhub.service.

   Verify the status of the service

   pi@qpi:~/qpi/libcint/build $ sudo systemctl status jupyterhub.service

   You should get something like

   ● jupyterhub.service - JupyterHub Service
   Loaded: loaded (/lib/systemd/system/jupyterhub.service; enabled; vendor preset: enabled)
   Active: active (running) since Sun 2021-05-23 15:57:45 CDT; 15s ago
   Main PID: 9578 (jupyterhub)
   Tasks: 11 (limit: 4915)
   CGroup: /system.slice/jupyterhub.service
          ├─9578 /usr/bin/python3 /usr/local/bin/jupyterhub --config=/root/jupyterhub_config.py
          └─9583 node /usr/bin/configurable-http-proxy --ip --port 8000 --api-ip 127.0.0.1 --api-port 8001 --error-target http://127.0.0.1:8081/hub/error
   May 23 15:57:48 qpi jupyterhub[9578]: 15:57:48.767 [ConfigProxy] info: Proxy API at http://127.0.0.1:8001/api/routes
   May 23 15:57:49 qpi jupyterhub[9578]: 15:57:49.319 [ConfigProxy] info: 200 GET /api/routes
   May 23 15:57:49 qpi jupyterhub[9578]: [I 2021-05-23 15:57:49.319 JupyterHub app:2778] Hub API listening on http://127.0.0.1:8081/hub/
   May 23 15:57:49 qpi jupyterhub[9578]: 15:57:49.325 [ConfigProxy] info: 200 GET /api/routes
   May 23 15:57:49 qpi jupyterhub[9578]: [I 2021-05-23 15:57:49.326 JupyterHub proxy:347] Checking routes
   May 23 15:57:49 qpi jupyterhub[9578]: [I 2021-05-23 15:57:49.327 JupyterHub proxy:432] Adding route for Hub: / => http://127.0.0.1:8081
   May 23 15:57:49 qpi jupyterhub[9578]: 15:57:49.333 [ConfigProxy] info: Adding route / -> http://127.0.0.1:8081
   May 23 15:57:49 qpi jupyterhub[9578]: 15:57:49.335 [ConfigProxy] info: Route added / -> http://127.0.0.1:8081
   May 23 15:57:49 qpi jupyterhub[9578]: 15:57:49.337 [ConfigProxy] info: 201 POST /api/routes/
   May 23 15:57:49 qpi jupyterhub[9578]: [I 2021-05-23 15:57:49.338 JupyterHub app:2853] JupyterHub is now running at http://:8000

   Open a web browser and point to: http://[Your Pi hostname or IP address]:8000/

   Then login using pi user and password

   

   You can go ahead and test that Qiskit is running on JupyterHub, by creating a new Python 3 file, and run the following

   pip list | grep qiskit

   you should get

   

4. Create the auto start script

   This script will auto start feh when the QPi start. for more details about that, please refer to Install Qiskit and feh

   create the folder

   pi@qpi:~ $ mkdir /home/pi/.config/autostart

   important : Choose a png file that you want your raspberry pi to display after starting up (like the chandelier in the video) rename it to and copy it to start.png and upload it to the Raspberry pi filesystem under the folder /home/pi/.config/autostart

   You can upload the file using any SFTP client like filezilla or SCP

   pi@qpi:~ $ mkdir /home/pi/.config/autostart
   pi@qpi:~ $ nano /home/pi/.config/autostart/start.sh

   and paste the following

   export DISPLAY=:0 
   mkdir -p /home/pi/qpi/tmp 
   cp /home/pi/.config/autostart/start.png /home/pi/qpi/figures/qpi.png 
   feh --scale-down --auto-zoom --fullscreen --reload 1 /home/pi/qpi/figures/qpi.png 
   unclutter -idle 0

   Type ctrl + x, then Y and enter to save the file and exit

   Then run the following command to make the script executable

   pi@qpi:~ $ chmod +x /home/pi/.config/autostart/start.sh

   and make it run at start up by executing

   pi@qpi:~ $ nano /home/pi/.config/autostart/start.desktop

   and pasting

   [Desktop Entry]
   Type=Application
   Name=Start
   Exec=/home/pi/.config/autostart/start.sh

   Type ctrl + x, then Y and enter to save the file and exit

Optional Configure the Raspberry Pi as an Access point

To use QPi without an internet connection, you can enable it as access point and connect via an Ethernet cable.

Important If your raspberry pi is connected to your network via Wi-Fi, you will need an additional USB Wi-Fi interface, otherwise you may lose connection to your raspberry through your LAN.

We used RaspAP

1. In case you did not already set up a Wi-Fi country, please run

   sudo raspi-config

   And navigate to 1 System Options -> S1 Wireless LAN and you will prompt to select a country. After that just cancel

2. Installing RaspAP

   pi@qpi:~ $ curl -sL https://install.raspap.com | bash

   Answer Y to all the question

3. Go to http://[Your Pi hostname or IP address]

   The default username and password are

   • Username : admin
   • Password : secret

4. Use the web interface to change them and save

   

5. To change the port of RaspAp run

   pi@qpi:~ $ sudo nano /etc/lighttpd/lighttpd.conf

   and locate

   server.port                 = 80

   Change it to

   server.port                 = 8080

   Type ctrl + x, then Y and enter to save the file and exit

   then reboot

   pi@qpi:~ $ sudo reboot

6. Verify that the changes to the port and credential worked by accessing http://[Your Pi hostname or IP address]:8080

   You can also change the SSID of you raspberry Pi, for more details please refer to RaspAP

Installing and running QPi

1. Installing QPi Library

   Download the whl file using the commands below. In case you are not able to use wget, please download the file QPi_lib-0.2.7-py3-none-any.whl and upload it to the QPi under the path /home/pi/qpi

   cd /home/pi/qpi
   wget https://github.com/zouppa/qpi/tree/main/QPi_Library/QPi_lib-0.2.7-py3-none-any.whl

   Install the library

   pip install QPi_lib-0.2.7-py3-none-any.whl

2. Running QPi

   Open a web browser and point to : http://[Your Pi hostname or IP address]:8000/

   Then login using pi user and password

   

   You can go ahead and create a new Python 3 file, and import the needed library

   import qpi_lib
   import warnings
   from qpi_lib import qsphere_funcs
   from qiskit import QuantumCircuit
   warnings.filterwarnings('ignore')

3. Create a circuit and draw it

   qc = QuantumCircuit(3)
   # Apply H-gate to the first:
   qc.h(1)
   qc.x(0)
   
   # Apply a CNOT:
   qc.cx(0,1)
   qc.cx(0,2)
   
   qc.z(0)
   qc.z(1)
   
   qc.draw(output='mpl')

4. To visualize any circuit on the QPi you can run

   qsphere_funcs.plot_qsphere_full(qc)

For more information, feel free to check the following links:

• Introduction to Qpi : a step-by-step guide to building your QPi
• Quantum Operations with Qpi : contains examples to start using your QPi

Feel free to reach out to the team:

• Zouppa : Mohamed Zouhaier Ramadhane

• Catalina Albornoz Anzola

• El Serch : Sergio Inurreta

• Ana Vialeny Mota Gómez

• Jaime Jesús Ambrosio Mallqui

This site is the result of the IBM Academy of Technology Initiative “Document and Publish the QPi Project”, report ARB-1328. For more information see the Initiative eCard.