Contributing to the Qiskit Code Itself: A Guide

IBM’s open source Quantum Information Science Kit Qiskit welcomes code contributors. You can be helpful to the project without having to be a physicist or a mathematician! Many issues raised by users against Qiskit code are easily handled by someone with good Python skills and a good attitude. It’s productive for the Qiskit team to have volunteer contributors like you submit pull requests on such issues, so your work is truly appreciated. If you run into any trouble, you can check out the “Contributing to Qiskit” page in the Qiskit documentation as well. If you plan on making contributions, please check the contributing file in each element to read over the per-project specifics — for example, this one.

Who should read this

You are a user of Qiskit and you want to hack on the Qiskit code itself. You already know about Python, GitHub repositories, and team open source projects. You already have your own GitHub account.

What you will learn

• You will identify the most important repositories in the Qiskit project.
• You will get a first idea of the layout of the Qiskit code.
• You will install the core Qiskit repositories in development mode.
• Some notes on how to get help on Qiskit.

Nature of Qiskit

The truths, mysteries, and paradoxes of quantum computing aside, here we are concerned with maintaining the scaffolding supporting a nascent science. Qiskit in its present form is transitory. When quantum computing fully takes shape, it may look very different. We labor in the dawn hours: impermanence renders our work more poignant, not less meaningful.

Structure of Qiskit

Informally, the Qiskit project contains three categories of repositories:

• Core Qiskit
• Providers
• Other Stuff

Core Qiskit is the code that allows us to prepare quantum computations, provides the hooks for interchangeable quantum computing execution backends, the Providers, characterize error and create and execute complex quantum algorithms.

Providers are plugins invoked through the core Qiskit code that relay quantum computations to simulators or to genuine quantum hardware and return the results. One provider repository in the Qiskit project, qisit-ibmq-provider, connects with IBM’s cloud simulators and hardware, and others with partners’ or competitors’ simulators and hardware.

Other Stuff consists of repositories that were started but mostly are archived. A Javascript implementation of parts of Qiskit. A GUI for experimenting with showcase algorithms coded early in Qiskit history. Et cetera. New repositories may spring up. Old repositories may be revived — you might be the coder who revives one. We don’t know where we are going because we’ve never been there before.

There is also the qiskit-community repository which has excellent contributions from outside the project, including the incomparable qiskit-textbook.

Qiskit Core

If you’re going to hack on Qiskit, you start by forking the following Qiskit repositories:

• Qiskit is the name of a specific repository in the Qiskit project. It’s mostly a loader for the others so that users can simply do pip install qiskit and pull in the code that really does stuff.
• Terra is the architectural framework for preparing quantum computations and processing them on hardware devices or simulators. It is math, it is compilation, it is job control, it is pulse control, and it offers a number of visualization facilities. Target backends, whether hardware or simulated, are interchangeable: Terra itself provides only the hooks for the various backends, whether IBM’s or those of third parties. An example of a third-party backend provider for Qiskit is Quantum Inspire.
• Aer is a simulator backend for Terra, or rather, a collection of simulation facilities, both CPU-based and GPU-based. It runs on your workstation. There’s another simulator in the cloud that you can reach through the IBM Q Provider (below), and others offered through third-party providers.
• Ignis is the statistical library for quantum error characterization and remediation.
• Aqua is the highest algorithmic level offered by Qiskit. Aqua offers showcase algorithms, but more fundamentally, it is the top-level framework against which the eventual “primitives” of deliverable quantum computing applications will be coded.

In the core repositories, the branch under development is typically the master branch, though other branches may be created when major changes are being prepared. If you are working on an issue, you’ll usually be working on master. If you get interested in helping on a major change to the code, you may get invited by the team to work in another branch.

Documentation Resources

• There are Jupyter notebooks on the fundamentals of Quantum Computing.
• Work your way through “the Textbook”, Learn Quantum Computation using Qiskit, in your spare time. This is again a series of Jupyter notebooks running on IBM Quantum Experience. Be aware you’ll spend more than a week on reading the Textbook (possibly months), don’t let it stop you from getting coding right away!
• The code-level Qiskit documentation is here. It has several quick tutorials about working with Qiskit. The API References are there, too, but they are high-level and auto-generated from code comments, so you will need to dig deeper to hack on the code. The code is always its own best documentation.

Online help resources

The main online help resources for working with Qiskit are the following:

• Qiskit Slack is where the Qiskit team and the Qiskit community hang out together and everyone helps one another.
• Quantum Computing Stack Exchange is where the scientists hang out and answer the deep questions.
• Qiskit on YouTube.

Getting Repositories Forked

We are going to install the Qiskit current release in a virtual environment then install again manually on top of the release installation from forked development repositories. We want forked repositories so we can make branches for our contributions, for example, bug fixes.

We fork each repository by starting at https://github.com/Qiskit, navigating to each repo, and clicking the Fork widget in the upper right.

GitHub Fork widget

• qiskit
• qiskit-terra
• qiskit-ibmq-provider
• qiskit-aer
• qiskit-ignis
• qiskit-aqua
• retworkx (this is a library that Terra and Aqua depend on which the Qiskit team would really like some help with!)

(I also keep around a fork of qiskit-tutorials and qiskit-textbook for my own benefit, but it’s not necessary.)

Create a development directory and underneath that directory, clone each of your new forks. Let’s say you are doing this in $HOME/DEV

In all that follows, we will assume you are in a Linux environment. If you need to install open source component outside Python on the Mac, I recommend doing so from MacPorts. On Linux, you will install open source components outside Python via one ofthe following depending on your distro:

• apt (Ubuntu …)
• yum (CentOS …)
• dnf (Fedora …)
• .. etc.

On Mac and Linux, I avoid Anaconda and work with “just plain” Python 3 in a virtual environment (you can do this in Windows too). We’ll see how to do that in a moment.

Installing release and then the forked code

Now we are going to

• Create on our local machine a new development virtual environment separate from any previous release environment we may have created.
• Install over it the code we have forked and cloned.
• If you need help, this process is also described in the Qiskit documentation here.

cd /some/directory
python3 -m venv qdev_env
. ./qdev_venv/bin/activate # the extra 'dot' (.) sources the activate file
cd /wherever/your/dev/source/is
cd qiskit-terra
python ./setup.py install
cd ../qiskit-ibmq-provider
python ./setup.py install
cd ../qiskit-aer
python ./setup.py install
cd ../qiskit-ignis
python ./setup.py install
cd ../qiskit-aqua
python ./setup.py install

Any time after that when you open a new shell and want to use this virtual environment, execute:

. /some/directory/qdev_venv/bin/activate

to activate in the new shell window the virtual environment so you have your installation at your fingertips.

And if you want to “jump out of” that virtual environment in a shell where it has been activated, just type deactivate and it will "go away" from that shell instance and restore your shell environment to pre-activate.

Feel free to install other tools in this virtual env you have created, such as spyder, the world-class Python editor/IDE. Or install spyder globally. (pip3 install spyder, of course.)

Notes

• If you switch branches in one of the Qiskit projects, it’s possible that you’ll need to rebuild to make sure that which is installed in the branch is your current work.
• The Qiskit team recommendation is to install your local git checkout into the venv with pip -e . (“dot” for “the project rooted in the current directory”, e.g, qiskit-terra) over your built install. pip -e just puts a link to the non-compiled elements of the code pointing back to your live editable source (hence -efor “editable”).
• Basically, my rule set is this (opinions differ): Install first with full install. After that use install -e for anything but Aer, always do full install for Aer. If you do an install with -e for Terra and have mysterious problems, do full install.
• If you’re working on qiskit-aer you will often need to recompile the code to reflect changes since most of Aer is written in C++, this can be done by rerunning the full install .
• And if things get really weird when you working on code, just delete your virtual environment and start again.

A discussion on Qiskit Slack about Jupyter and virtual environments

Dev E. Loper: @jax It works! But I have another issue. If I wish to run and test the code in a Jupyter notebook, do I have to install it in the virtual environment?

Jack Woehr: It depends on how Jupyter is installed.

• If it is installed in your global or user environment, and you created your virtual enviroment with python -m venv /some/dirpath --system-site-packages then the site packages are linked in, and Jupyter with them.
• If Jupyter was not installed that way and/or you did not use --system-site-packages creating the virt env, then you must pip install jupyter in the virt env.

I like the clarity of not using --system-site-packages so I install Jupyter in the virt env.

You’re new to Quantum Computing with IBM Qiskit and are eager to make progress. Each roadblock feels to you like a kick in the stomach. You want help, and fast, so you run to IBM Qiskit Slack. How do you get the answers you need?

Recent IBM Qiskit events have drawn thousands of participants. This morning there are 12,699 subscribers to the IBM Qiskit Slack #general channel.

We’re all eager. We’re all in a hurry to learn. Here are a few simple guidelines to insure that IBM Qiskit Slack maintains a high signal-to-noise ratio as source of information, inspiration, and interaction with the top talents in the field.

1. Choose a channel. The little + sign in the left column next to the word “Channels” (or whatever in your local language, e.g., “Canais” em portugues) shows you all the available channels, including ones you may not know exist. If your questions is about Qiskit Open Pulse, post in #open-pulse. If it’s a question about Terra, post in #qiskit-terra. If it’s about the Composer in IBM Q Experience, post in #ibm-q-experience. If you don’t know where to post, simply post in #general. Everyone reads #general.
2. Ask in a public channel, not a private message. If you ask your question in a private message, then the answerer must post the same answer again the next time the question is asked. Be fair and share! It saves work.
3. Patience, post once. Please DO NOT post your question in multiple channels, it just makes Slack more difficult to read! Please DO NOT use mass-address shorcuts like the @here address which blasts your comment to over 12,000 people, most of whom will simply be annoyed! There are dozens of IBM Qiskit team members who regularly browse the Slack channels. There are probably another 200+ Qiskit Advocates also participating. And of course, there are your (thousands of) peers who are happy to demonstrate their erudition in answering your question. But not everyone lives in the same time zone, nor is everyone online every day. The best person to answer your question may not see the question for a day or two, especially over the weekends. And again, your best chance to get intelligent eyes on your question is covered in Tip #1 above!
4. If you have a code question, post a working (or breaking) example. If you don’t, the first response you will get (from me, at least!) is “Post code, please!” I don’t want to think, I want to try your code example and only start thinking if it doesn’t work for me. If your code is a few lines, post it as a code block inline in your message. If it’s longer than message length, attach a file of your code to your message.
5. Post the error output. Sometimes code breaks for environmental reasons. Your code may run for others, but not for you. Give people a chance to see what you’re experiencing.
6. Describe your environment. Windows? Linux? Python version? mod venv or Anaconda? Qiskit levels for all components? Recently upgraded or downgraded a dependency such as scipybecause it works so well with something else you are working on? Etc.
7. DON’T PANIC … We’re all riding in the same spaceship and are all helping each other!

Towel Day in Innsbruck, Austria. Wikimedia Commons, Gnu Free Documentation License, Beny Shlevich