The logic for me on this is simple: quantum computers are extremely exciting, therefore I want one.

What’s so exciting about them? Everything associated with quantum science is both mysterious and intuitively unbelievable! I mean, there’s superposition — the notion that something can simultaneously be in two different states but when observed it will with certainty take on one or the other with random but mathematically predictable likelihood. Wow! And what about entanglement — the notion that two particles can be spookily (Einstein thought so) connected in such a way that regardless of where they are in the universe, if we observe the state of one of them then we will know with certainty what state we will observe in the other. Furthermore, this can occur without any information being transferred between them (we know this because they can exhibit this coherence faster than light could travel between them). An ever-growing mountain of experimental evidence supports these outlandish notions too. Also, if the claims of the largest companies building quantum computers can be believed, they are rapidly heading toward “quantum supremacy”, the point at which quantum computers will outperform the most powerful “classical” computers in selected domains. Hopefully now you are wondering just how can you get your hands on one of these babies? Well then please read on, my friend…

I am going to show you how you can easily setup your very own quantum computer simulator in your own home or office, for free! Why a simulator? Well, the real thing is likely to cost millions of US dollars, so a simulator will have to be sufficient for now. Fortunately IBM has given us the technology for this: the Qiskit open source software. Qiskit provides a complete set of tools for you to use to learn about quantum computing, including a quantum computer simulator. I have built this software into a Docker container to make it easy to use on almost any computer from a Raspberry Pi to your MacOS or Windows laptop. I may have gone a little far in creating mine, because I wanted mine to look like the machine above. So I made some 3D models and 3D printed this housing for the Raspberry Pi 4B that is my own quantum simulator:

If you are interested in printing this housing (which is completely unnecessary), the 3D models I built for it are here: https://www.tinkercad.com/things/0tEbcpVzFRI
Now let’s build your household quantum simulator (no housing required!)
There are really just 1 or possibly 2 steps:
- If you don’t already have Docker on your computer, then you will need to install that first.
- Then you can simply execute a “
docker run …
” command.
And that’s it! Easy, right?
Don’t worry, I’ll guide you through everything…
Docker First
If you have Docker installed already on your computer, you should be able to run the command below in a terminal window:docker ps
If that works, then please move on to the section titled, “Qiskit“, below.
On the other hand if you see a “permission denied
” error, then that means Docker is installed, but you have not fully configured your user account to use Docker. If that’s the case, please move ahead to “Permission Denied” below.
Otherwise, if you see a message that says something like, “command not found: docker
“, then Docker is not installed, so let’s fix that. On MacOS or Windows computers you will need to install Docker Desktop. Docker Desktop requires virtualization support, because it creates a well-hidden Linux VM under the covers in which Docker is installed and upon which your containers will run. Docker Desktop installation is very straightforward and the free installer download and instructions are here:
https://www.docker.com/products/docker-desktop
To install Docker on a Linux host instead, usually you can just use the command below:curl -sSL https://get.docker.com/ | sh
If you get an error saying “curl
” is not installed (i.e. “not found
“) then you will need to use your Linux system’s package manager to install “curl
” first (e.g., “apt install curl
“, “yum install curl
“, or similar). Then once curl is installed, run the above command again.
When the installation is finished, test it with:docker ps
Likely you will get a “permission denied
” error at that point, so we’ll fix that in the following section.
Permission Denied
Docker is usually installed in a manner that requires root permission, or membership in the “docker
” group, in order to use it. That’s inconvenient, so if you are seeing a permission error, you can usually resolve this by adding group “docker
” to your user ID with the command below:sudo usermod -aG docker $USER
After you run that command you need to exit the current shell and open a new shell in order for the new group to be usable.
Once the permissions are configured properly you should be able to execute this command without error:docker ps
Qiskit
Okay, Docker is all setup, so now you can run my Qiskit container! If you would rather build the container yourself, please see the section below called, “Rolling Your Own” and I will guide you through building the container for yourself. Otherwise, if you just want to use the one I have already built, then run one of the commands below, except replace “my_token
” with a password that you will have to use when accessing your quantum computer simulator.
On an ARM host (e.g. a Raspberry Pi model 2, 3, or 4) use:docker run -d -e JUPYTER_TOKEN=my_token -p 8888:8888 --restart unless-stopped ibmosquito/qiskit_arm32:1.0.0
On an x86 host (e.g., any Intel Mac, any Windows machine, or any x86 Linux host) use:docker run -d -e JUPYTER_TOKEN=my_token -p 8888:8888 --restart unless-stopped ibmosquito/qiskit_amd64:1.0.0
It will take a while to download this docker container, but when the download is complete it will start running. Once it is running, you will be able to see it in the output of the “docker ps
” command.
Start Playing!
Once the container starts up you can point your favorite web browser to this computer’s port 8888
to login and start using python in Jupyter to program your quantum computer simulator. Once you have logged in you should see the usual Jupyter interface with one example. You can open the example, and use the usual method to click in each execution frame and hit “Control-Enter
” to execute it and verify everything is installed and working correctly.

Rolling Your Own
If you wish to build the container for yourself, that’s easy too. You will need to install “git
” and “make
” if they are not already installed on your system. For example, “apt install git make
” or “yum install git make
“.
Then begin by cloning my GitHub repository, and “cd” into it:git clone https://github.com/MegaMosquito/qiskit.git
You then need to edit the “Makefile
” to put your own values into the 2 variables defined at the top:JUPYTER_TOKEN=secr3t
DOCKERHUB_ID=ibmosquito
Replace “secr3t
” with your own choice of password for access to the web server Jupyter Notebook.
If you intend to eventually push this to DockerHub you will need to replace my DockerHub ID, “ibmosquito
“, with your own DockerHub ID. If you don’t have one, you can get one for free, here: https://hub.docker.com/signup/.
Then simply run this command:make build
Once that’s done, you can run it with:make run
Once you do that, you can use your browser to connect to this machine, at port 8888
. E.g., using this URL:http://ADDRESS:8888/
(where “ADDRESS
” is the IP address or hostname of this computer).
If you want to push your container to DockerHub (totally optional) you need to first login to your DockerHub account:docker login
and then you can:make push
To Learn More…
This YouTube video gives a brief QISKIT primer: https://www.youtube.com/watch?v=V3hXSftZuoc
I took the quantum NOT gate example from this set of guided exercises: https://github.com/JavaFXpert/qiskit4devs-workshop-notebooks
The IBM Quantum Experience getting started guide is here: https://quantum-computing.ibm.com/docs/
The official QISKIT documentation is here: https://qiskit.org/documentation/
Historical Stuff
I personally enjoyed reading about the early days of quantum mechanics in the 1920s. If you think you would enjoy that too, here’s a very brief history and some other background I found interesting.
“God does not play dice” (Albert Einstein).

Imagine a time back between the first and second world wars… The world’s most famous physicist, Albert Einstein was being confronted with the new ideas of Quantum Mechanics and he just could not accept the implications of these theories. Einstein, and his most famous writings on Special Relativity, and the views many of his fellow physicists (including Boris Podolsky and Nathan Rosen) were bumping up against an upstart group of physicists with some radical new ideas. Werner Heisenberg’s Uncertainty Principle, Niels Bohr’s Wave-Particle Duality, Erwin Schrödinger’s cat being both alive and dead at the same time, and perhaps most shocking of all, the implications of particle entanglement. These unsettling new ideas were challenging the most established physics doctrines of the time. Einstein famously derided this science with statements like, “God does not play dice”, and calling quantum entanglement, “spukhafte Fernwirkung” (spooky action at a distance).
Irrational, chaotic, random — but correct!
As time passed after those first intense and public disagreements (most notably between Borh and Einstein) experimental physicists slowly began to provide validation for the theoretical concepts of Quantum Mechanics. Mathematician Paul Durac was also able to unify aspects of Special Relativity together with Quantum Mechanics (Durac’s Equation) helping to confirm that these two views of the universe are not necessarily contradictory. We also now know that entanglement certainly occurs, and it enables the almost instantaneous transmission of information between entangled particles regardless of their locations in the universe. Roll forward to the last few years and faster-than-light communication between entangled particles has been independently verified experimentally by several physicists.
So What?
I’ve been reading about this in the popular press and Wikipedia for years. Theoretical and experimental physics are both fascinating, but somewhat inscrutable to me. As a Computer Scientist, what I find most exciting is the that Quantum Mechanics suggests the possibility of a quantum computer. That is, quantum superposition (being probabilistically in both of two states until measured) and quantum entanglement, together can be used to perform useful computations. For example Peter Shor famously showed how these primitives could be used to perform integer factorization incredibly quickly. That of course put fear into the hearts of everyone using RSA encryption (which is based on the difficulty of factoring large integers). So the race was on to actually build one of these things.
Enter The Big Kids
Recently, several well-funded entities (large corporations and governments) have invested many millions of dollars trying to build reliable, stable, quantum computers based on quantum circuits. These quantum circuits are formed of quantum gates, which are conceptually similar to the logic gates in classical computers. The data moving through the gates in the circuit are quantum bits (or “qubits”). Like their analogs (binary “bits”) in the classical computing world, qubits when measured always have the value 0 or 1. However, their state before measurement is much more interesting. There are also quantum annealing computers, but they are less interesting to me because it appears there will be much greater constraints on their applicability.
Qubits, superposition, entanglement — oh my!
Qubits moving through the gates of a quantum circuit can be in a quantum state or superposition. An explanation of these I will not attempt to make except to say that that qubits are simultaneously in both 0 and 1 state, linear combinations of the two, each of them with some probability of being the observed when its state is measured.
Modern quantum circuit computers at the time of writing are limited in terms of the number of qubits they support, and perhaps more significantly by quantum decoherence and the resulting difficulty of distinguishing signal from noise. Error correction is therefore an important consideration for these machines. They usually also require supercooling, down to small fractions of a degree above zero Kelvin, which is difficult to acheieve, and then to stabilize.
Practical Use
One of the main reasons I wanted to set up a quantum simulator in my home was so I could start experimenting with quantum programming. So far it seems difficult for me to imagine how I can perform any useful algorithms within these constraints. So far the basic exercises I have tried just manipulate qubits through gates of various types in my quantum circuit to solve rather contrived and quantum-gate-specific problems. Now that I have my own simulator I will work to overcome this very steep initial learning curve. Eventually I hope I will become able to imagine how I could construct solutions to real world problems with this technology. I hope you will find your new quantum simulator useful for this too!
If you try it out I’d love to hear about it.