├── .all-contributorsrc
├── .github
└── workflows
│ ├── docker-image.yml
│ └── docker-tag.yml
├── .gitignore
├── Dockerfile
├── LICENSE
├── README.md
├── article.md
├── build
├── config_git.sh
└── requirements.txt
├── container-what-is-container.png
├── data
├── README.md
└── share
│ └── README.md
├── ql.PNG
├── start.sh
└── start_jupyter.sh
/.all-contributorsrc:
--------------------------------------------------------------------------------
1 | {
2 | "files": [
3 | "README.md"
4 | ],
5 | "imageSize": 100,
6 | "commit": false,
7 | "contributors": [
8 | {
9 | "login": "mickahell",
10 | "name": "Mica",
11 | "avatar_url": "https://avatars.githubusercontent.com/u/20951376?v=4",
12 | "profile": "https://github.com/mickahell",
13 | "contributions": [
14 | "code",
15 | "doc"
16 | ]
17 | },
18 | {
19 | "login": "MaldoAlberto",
20 | "name": "Alberto Maldonado",
21 | "avatar_url": "https://avatars.githubusercontent.com/u/21325664?v=4",
22 | "profile": "https://www.linkedin.com/in/albertomaldonadoromo/",
23 | "contributions": [
24 | "review"
25 | ]
26 | }
27 | ],
28 | "contributorsPerLine": 7,
29 | "projectName": "quantum_lab",
30 | "projectOwner": "mickahell",
31 | "repoType": "github",
32 | "repoHost": "https://github.com",
33 | "skipCi": true
34 | }
35 |
--------------------------------------------------------------------------------
/.github/workflows/docker-image.yml:
--------------------------------------------------------------------------------
1 | name: Docker Image CI
2 |
3 | on:
4 | push:
5 | branches: [ main ]
6 | pull_request:
7 | branches: [ main ]
8 |
9 | jobs:
10 |
11 | build_qiskit:
12 | runs-on: ubuntu-22.04
13 | steps:
14 | - uses: actions/checkout@v2
15 | - name: Build the Docker qiskit
16 | run: docker build . --file Dockerfile --tag quantum_lab_qiskit:main
17 |
--------------------------------------------------------------------------------
/.github/workflows/docker-tag.yml:
--------------------------------------------------------------------------------
1 | name: Docker TAG CI
2 |
3 | on:
4 | workflow_dispatch:
5 | push:
6 | tags:
7 | - '*'
8 | jobs:
9 |
10 | build_qiskit:
11 | runs-on: ubuntu-22.04
12 | steps:
13 | - uses: actions/checkout@v2
14 | - name: Set env
15 | run: echo "RELEASE_VERSION=${GITHUB_REF#refs/*/}" >> $GITHUB_ENV
16 | - name: Build qiskit and push to Docker Hub
17 | env:
18 | DOCKERHUB_PASS: ${{ secrets.DOCKERHUB_PASS }}
19 | run: |
20 | docker build . --file Dockerfile --tag mickahell/quantum_lab_qiskit:${RELEASE_VERSION}
21 | docker tag mickahell/quantum_lab_qiskit:${RELEASE_VERSION} mickahell/quantum_lab_qiskit:latest
22 | docker login --username=mickahell --password=${DOCKERHUB_PASS}
23 | docker push mickahell/quantum_lab_qiskit --all-tags
24 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | # ignore files and folders into git
2 | data/share
3 | *.DS_STORE
4 |
--------------------------------------------------------------------------------
/Dockerfile:
--------------------------------------------------------------------------------
1 | FROM mickahell/qatcomputer-full:latest
2 |
3 | # Var for labels
4 | ARG GITHUB_ACTOR
5 | ARG GITHUB_REPOSITORY
6 | ARG GITHUB_REF
7 |
8 | ARG DEBIAN_FRONTEND=noninteractive
9 | ENV TZ=Europe/Paris
10 |
11 | LABEL org.opencontainers.image.title="Quantum Lab" \
12 | org.opencontainers.image.authors=${GITHUB_ACTOR} \
13 | org.opencontainers.image.vendor=${GITHUB_REPOSITORY} \
14 | org.opencontainers.image.source="https://github.com/mickahell/quantum_lab" \
15 | org.opencontainers.image.url="https://github.com/mickahell/quantum_lab/tags" \
16 | org.opencontainers.image.description="Docker image for quantum algorythm" \
17 | org.opencontainers.image.documentation="https://github.com/mickahell/quantum_lab/blob/main/README.md" \
18 | org.opencontainers.image.os="Ubuntu Focal" \
19 | org.opencontainers.image.version=${GITHUB_REF}
20 |
21 | # OS requirements
22 | RUN apt-get update -yq \
23 | && apt-get install -yq \
24 | python3-tk \
25 | graphviz \
26 | git \
27 | && apt-get dist-upgrade -yq \
28 | && apt-get clean -yq
29 |
30 | # Add script & data
31 | ADD build/* /opt/quantum_lab/build/
32 | ADD data/ /opt/quantum_lab/data/
33 | ADD start_jupyter.sh /opt/quantum_lab/
34 |
35 | # General & env requirements
36 | RUN pip install --upgrade pip setuptools
37 | RUN pip install -r /opt/quantum_lab/build/requirements.txt
38 |
39 | WORKDIR /opt/quantum_lab/data
40 | VOLUME /opt/quantum_lab/data/share
41 |
42 | EXPOSE 8888
43 |
44 | CMD /bin/bash
45 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2021 Mica
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Quantum Lab
2 |
3 | [](#contributors-)
4 |
5 | [](https://zenodo.org/badge/latestdoi/343446026)
6 | [](https://github.com/mickahell/quantum_lab/actions/workflows/docker-image.yml)
7 | [](https://github.com/mickahell/quantum_lab/actions/workflows/docker-tag.yml)
8 | [](https://github.com/mickahell/quantum_lab/releases)
9 |
10 | [](https://hub.docker.com/r/mickahell/quantum_lab_qiskit)
11 |
12 | __The next images are now depreciated, please use the Qiskit one just above.__
13 | - Old images
14 |
15 | [](https://hub.docker.com/r/mickahell/quantum_lab_qiskit-full)
16 | [](https://hub.docker.com/r/mickahell/quantum_lab_qml)
17 | [](https://hub.docker.com/r/mickahell/quantum_lab_qsharp)
18 | [](https://hub.docker.com/r/mickahell/quantum_lab_myqlm)
19 | [](https://hub.docker.com/r/mickahell/quantum_lab_simulaqron)
20 | [](https://hub.docker.com/r/mickahell/quantum_lab_cirq)
21 |
22 | Linux
26 | apt-get install docker-ce docker-ce-cli containerd.io
27 | Mac / Windows
30 | https://www.docker.com/products/docker-desktop
31 | Quantum Lab: Docker image for quantum laboratory, Michaël Rollin, 2021, DOI: 10.5281/zenodo.4664195
72 |
73 | ## Contributors ✨
74 |
75 | Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
76 |
77 |
78 |
79 |
80 |
86 |
87 |
88 |
89 |
90 |
91 |
92 | This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
93 |
--------------------------------------------------------------------------------
/article.md:
--------------------------------------------------------------------------------
1 | # Quantum Lab
2 | A simple docker image to simulate a full *Quantum laboratory*
3 |
4 | ## Abstract
5 | We are at the beginning of the run for the quantum supremacy and quantum independent of the different worldwide government. More and more companies are building their own quantum computer with their own library/language. Some of these allow to connect to multiple quantum computers and other are specializes for one type of computer. Also, some libraries are very specified for some kind of task like PennyLane for Quantum Machine Learning (QML).
6 |
7 | For these reason it begins complicated to set up a clear unique environment to develop with each quantum technologies or to switch between each others. This article is about the setup of a simple multi-Docker image, allowing to build a clean environment for each technology's known and a sharable volume to share the content between the host computer and the different container.
8 |
9 | ## Table of content
10 | 1. [Pre-requisites](#prereqisites)
11 | 2. [What's Docker ?](#docker)
12 | 3. [How does it work](#working)
13 | 3.1. [Building image](#image)
14 | 3.2. [Create container](#container)
15 | 3.3. [Run everything together](#run)
16 | 4. [Future](#future)
17 | 4.1. [Live platform](#live)
18 | 6. [Annexes](#annexes)
19 | 7. [References](#ref)
20 |
21 | ## 1. Pre-requisites
22 | First to be able to run the lab, you need to install Docker[[6]](#6), that's the only requirement needed :
23 | - Linux
24 | apt-get install docker-ce docker-ce-cli containerd.io
25 | Refer to https://docs.docker.com/engine/install/ubuntu/
Mac / Windows
28 | https://www.docker.com/products/docker-desktop
29 |
34 |
35 |
36 | | Docker is a technology allowing OS virtualization and system simulation. It allows to generalize a simple application with its whole environment into a deployable package to be share and run everywhere on every computer supporting Docker. This package is calling a container, the container is OS-level virtualization and every container share their own kernel. Moreover, the container is fully isolated from the host application. |
37 |  |
38 |
39 |
40 |
41 |
42 | ## 3. How does it work
43 |
44 |
45 |
46 |
47 |  |
48 | The role of the image is to simulate a virtual environment as a Quantum lab for a specialized library/language. Another need is to synchronize the data between the container of the host computer.
Like this, we could develop our code on our favorite IDE on our classical computer and run the code directly in the container.
Download the code : Github |
49 |
50 |
51 |
52 |
53 | ### 3.1. Build the image
54 | First we need to build the image, we have to generate a docker image from our `Dockerfile` by using :
55 | docker build --build-arg quantum_env=qiskit.sh -t quantum_lab .
56 | Feel free to replace `qiskit.sh` with `qml.sh`, `qsharp.sh`, `simulaqron.sh`, `myqlm.sh` or `cirq.sh`. That'll set up a specialized environment for each library/language. This command can take several minutes, do not stop it until the command gave you the hand back.
57 |
58 | #### Pre-build images
59 | Pre-build images for each environment are available in the [Docker Hub](https://hub.docker.com/search?q=mickahell%2Fquantum&type=image) :
60 | - `quantum_lab_qiskit`
61 | - `quantum_lab_qml`
62 | - `quantum_lab_qsharp`
63 | - `quantum_lab_simulaqron`
64 | - `quantum_lab_myqlm`
65 | - `quantum_lab_cirq`
66 |
67 | You can download them by using : `docker pull mickahell/[IMAGE_NAME]` (ex. `quantum_lab_qiskit`)
68 | To not have any problem with the following tutorial I suggest you to rename the image as `quantum_lab` by using : docker image tag mickahell/[IMAGE_NAME]:latest quantum_lab:latest
69 |
70 | Now if you tape `docker images` you'll be able to see your image :
71 |
72 | REPOSITORY TAG IMAGE ID CREATED SIZE
73 | quantum_lab latest 73cc092474d1 3 weeks ago 1.48GB
74 | mickahell/quantum_lab_qiskit latest 73cc092474d1 3 weeks ago 1.48GB
75 | ubuntu 18.04 329ed837d508 4 weeks ago 63.3MB
76 |
77 |
78 | ### 3.2. Create container
79 | Now we have our image `quantum_lab`, you can see it by taping `docker images`. Next we need to set up a container who we be our virtual environment. We can create as much container as the stockage of our computer allows it.
80 |
81 | #### Volume
82 | To sync data between the container and the host computer we need to create a volume, by default in the image a simple volume is created between the default docker sharing folder of the host and the `/opt/quantum_lab/data/share` folder. To make things easier we can specify which folder of our host we want to sync by using `-v [YOUR_FOLDER]:/opt/quantum_lab/data/share` during the creation of the container.
83 |
84 | #### Jupyter
85 | In each environment Jupyter notebook is available, to synchronize it with our host browser we need to sync port network to do this just use the option `-p 8888:8888` in the container creation. Then a script allow you to start a Jupyter server : `/opt/quantum_lab/data/start_jupyter.sh`.
86 | Finally, just go in your browser and tap : `http://127.0.0.1:8888/`
87 |
88 |
89 | ### 3.3. Run everything together
90 | To create our container and to be allowed using volume sync and jupyter you can use this simple command line :
91 | docker run -it -v $(pwd)/data:/opt/quantum_lab/data/share --entrypoint=/bin/bash -p 8888:8888 -e LANG=C.UTF-8 quantum_lab
92 |
93 | ## 4. Future
94 | We are at the very beginning of the quantum era, so that means the already installed quantum technologies will have updated very often and more and more libraries and languages will be coming soon. So the image will be updated as often as possible and more environment will be soon available as a new option.
95 |
96 | The goal is to make everything possible to keep the image as simple as possible to use and to set up. Pre-build image are already available in the [Docker Hub](https://hub.docker.com/search?q=mickahell%2Fquantum&type=image), allowing to just download the image and create container, so no need to clone the project and build entirely the images anymore.
97 |
98 | Also, the experiences part will be externalized in another GitHub repository and download automatically in the build phase, in order to keep the Docker image clean without too much _random_ data.
99 |
100 | If you have an idea of features do not hesitate and create an **[issue](https://github.com/mickahell/quantum_lab/issues/new)**.
101 |
102 | ## 4.1. Live platform
103 | A live version is available directly in your browser for prototype, testing experiments and science vulgarisation/demo. Also presenting how to use the image to create Quantum application to deploy everywhere --> https://quantum-lab.xtraorbitals.xyz
104 |
105 | ## 5. Annexes
106 | ### Environment details
107 |
108 | - Library's (libs) common for every env : ```networkx, numpy, matplotlib, notebook, pandas, scipy, tk, vim```
109 | - 4 libs setup are available, one for installating Qiskit[[1]](#1), one for using Pannylane[[2]](#2), one for using Q#[[3]](#3), one for SimulaQron[[4]](#4), another for myQLM[[5]](#5) and for Cirq[[7]](#7)
110 | - `qml.sh`
111 | - Libs : ```autograd, pennylane, pennylane-sf, pennylane-qiskit```
112 | - `qiskit.sh`
113 | - Libs : ```qiskit, qiskit[visualization], qiskit-nature```
114 | - `qsharp.sh`
115 | - Libs : ```qsharp, iqsharp```
116 | - `simulaqron.sh`
117 | - Libs : ```simulaqron```
118 | - `myqlm.sh`
119 | - Libs : ```myqlm, libmagickwand-dev, myqlm-interop[qiskit_binder]```
120 | - `cirq.sh`
121 | - Libs : ```cirq, cirq-core[contrib], texlive-latex-base, latexmk```
122 |
123 | All the libs setup scripts are available in the folder `/opt/quantum_lab/build` inside the image, some of the libs can live together and some cannot (ex. `qiskit` and `pennylane-qiskit` can't).
124 |
125 | #### Protocols for experiencing Quantum
126 | **COMING SOON !**
127 |
128 | ### Hello world!
129 | *Hello world* program for each environment are available inside the image in the data folder and allow to test the quantum laboratory.
130 |
131 | ### Simple docker commands
132 | - List the existed images : `docker images`
133 | - List the existed container : `docker ps -a`
134 | - The `-a` is used to show every existed containers, that's include the stopped one
135 | - To start a container : `docker start [CONTAINEUR_ID]`
136 | - To go inside a started container : `docker exec -it -u root [CONTAINEUR_ID] /bin/bash`
137 | - Delete container : `docker rm [CONTAINEUR_ID]`
138 | - Delete stopped container : `docker container prune`
139 | - Delete image : `docker rmi [NAME_OF_THE_IMAGE]`
140 | - You can use `-f` to force the suppression and delete the containers associated to the image
141 | - List the existed volume : `docker volume ls`
142 | - Delete volume not used anymore : `docker volume prune`
143 |
144 | ## 6. References
145 | [1] [Qiskit](https://qiskit.org): An Open-source Framework for Quantum Computing, 2019, [DOI: 10.5281/zenodo.2562110](10.5281/zenodo.2562110)
146 | [2] [Pennylane](https://pennylane.ai): Automatic differentiation of hybrid quantum-classical computations, 2018, [DOI: arXiv:1811.04968](https://arxiv.org/abs/1811.04968)
147 | [3] [Q#](https://azure.microsoft.com/fr-fr/resources/development-kit/quantum-computing/): The Microsoft Quantum Development Kit Preview, 2017
148 | [4] [Simulaqron](http://www.simulaqron.org/): A simulator for developing quantum internet software, 2018, [DOI: 10.1088/2058-9565/aad56e](https://doi.org/10.1088/2058-9565/aad56e)
149 | [5] [AQASM](https://atos.net/en/lp/myqlm): Atos Quantum Assembler, 2021, [DOI: arXiv:2102.12973](https://arxiv.org/abs/2102.12973)
150 | [6] [Docker](https://www.docker.com), An introduction to Docker for reproducible research, 2015, [DOI: 10.1145/2723872.2723882](https://doi.org/10.1145/2723872.2723882)
151 | [7] [Cirq](https://quantumai.google/cirq): An open source framework for programming quantum computers, 2018
152 |
153 | ## Author
154 | Michaël Rollin, [GitHub](https://github.com/mickahell), [Twitter](https://twitter.com/mickahell89700), [Linkedin](https://www.linkedin.com/in/michaelrollin/)
155 | ### Cite as
156 | If you use my work, please cite as : Quantum Lab: Docker image for quantum laboratory, Michaël Rollin, 2021, DOI: 10.5281/zenodo.4664195
157 |
--------------------------------------------------------------------------------
/build/config_git.sh:
--------------------------------------------------------------------------------
1 | #!/bin/bash
2 |
3 | # If you want to use and configure git, fullfill the next lines with your GitHub/GitLab information
4 | git config --global user.email « mail »
5 | git config --global user.name « username »
6 |
--------------------------------------------------------------------------------
/build/requirements.txt:
--------------------------------------------------------------------------------
1 | matplotlib
2 | pylatexenc
3 | notebook
4 |
--------------------------------------------------------------------------------
/container-what-is-container.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/mickahell/quantum_lab/b3f44a5d3890dbbc443f06576feb6e6461e3e57b/container-what-is-container.png
--------------------------------------------------------------------------------
/data/README.md:
--------------------------------------------------------------------------------
1 | # Data
2 | - The `share`folder is sync with your host folder
3 | - You can work on your host IDE and run your program inside the container
4 |
5 | ## Sharing file
6 | - File sync with your host computer
7 |
8 | ## Jupyter
9 | - To start the jupyter server, run the script `./start_jupyter.sh`
10 | - Then go to your host browser and tape `http://127.0.0.1:8888/`
11 |
--------------------------------------------------------------------------------
/data/share/README.md:
--------------------------------------------------------------------------------
1 | # Share
2 | - Files sync with your host computer
3 |
--------------------------------------------------------------------------------
/ql.PNG:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/mickahell/quantum_lab/b3f44a5d3890dbbc443f06576feb6e6461e3e57b/ql.PNG
--------------------------------------------------------------------------------
/start.sh:
--------------------------------------------------------------------------------
1 | #!/bin/bash
2 |
3 | docker run -it -v $(pwd)/data/share:/opt/quantum_lab/data/share --entrypoint=/bin/bash -p 8888:8888 -e LANG=C.UTF-8 quantum_lab
4 |
--------------------------------------------------------------------------------
/start_jupyter.sh:
--------------------------------------------------------------------------------
1 | #!/bin/bash
2 |
3 | jupyter notebook --allow-root --port=8888 --no-browser --ip='*' --NotebookApp.token='' --NotebookApp.password=''
4 |
--------------------------------------------------------------------------------
