An Qiskit mitwirken¶

Qiskit ist ein Open-Source-Projekt mit dem Ziel Menschen aller Alters- und Berufsgruppen die Nutzung von Quanteninformationstechnologien zu ermöglichen. Diese Seite beschreibt wie man sich der Qiskit-Gemeinschaft anschließen kann.

Wo sich die Qiskit-Bestandteile befinden¶

Der Qiskit Quellcode befindet sich in dem Qiskit-Github-Repository. Dort können die einzelnen Bestandteile die Qiskit ausmachen gefunden werden. Unter anderem sind dies

Erste Schritte¶

Erfahren wie Mitglieder der Qiskit-Gemeinschaft

Bugs melden und Verbesserungen vorschlagen¶

Falls ein Problem auftritt, sollte ein Issue im entsprechenden Issue-Tracker eröffnet werden:

Element	Issue-Tracker
qiskit-terra	https://github.com/Qiskit/qiskit-terra/issues
qiskit-aer	https://github.com/Qiskit/qiskit-aer/issues
qiskit-ignis	https://github.com/Qiskit/qiskit-ignis/issues
qiskit-aqua	https://github.com/Qiskit/qiskit-aqua/issues
Dokumente oder Qiskit Meta-Pakete	https://github.com/Qiskit/qiskit/issues

Falls man eine Idee für ein neues Funktion hat, sollte ein Enhancement-Issue im entsprechenden Issue-Tracker eröffnet werden. Wenn ein neues Issue eröffnet wird, wird eine Diskussion gestartet ob diese Idee in das Projekt passt, wie sie implementiert werden kann, etc.

Code Beisteuern¶

Styleguide¶

Um einen konsistenten Code-Stil in dem Projekt sicherzustellen werden Pylint und pycodesytle verwendet um zu überprüfen ob Code-Beiträge konform sind und den Styleguide respektieren. Um zu überprüfen ob Änderungen mit dem Styleguide konform sind, den folgenden Befehl ausführen: tox -elint

Contributor License Agreement (Mitwirkenden-Lizenzvereinbarung)¶

Bevor neuer Code beigesteuert werden kann müssen alle Mitwirkenden die „Contributer License Agreement“ (CLA) (Mitwirkenden-Lizenvereinbarung) unterscheiben. Mit dem Unterzeichnen der CLA bestätigt man, dass man Autor des Code-Beitrags ist, und dass man diesen unentgeltlich entsprechend der Apache-2.0 Lizenz beisteuert.

Wenn man an einem Qiskit-Projekt mit einem Pull-Request mitwirkt prüft ein Bot ob die CLA unterzeichnet wurde. Falls nötig wird der Bot den Pull-Request kommentieren - inklusive eines Links zum Akzeptieren der Vereinbarung. Die CLA für natürliche Personen ist zur Überprüfung als PDF-Datei verfügbar.

Bemerkung

Falls ein Beitrag einem Beschäftigungsverhältnis entstammt oder Eigentum des Arbeitgebers ist, ist es sehr wahrscheinlich, daß eine CLA für Unternehmen unterzeichnet werden muss, und per E-Mail an <qiskit@us.ibm.com> geschickt werden muss.

Pull-Requests¶

Wir verwenden GitHub Pull-Requests um Beiträge zu akzeptieren.

Obwohl nicht zwingend benötigt sollte ein Issue bzgl. dem Bug oder dem Feature an welchem man arbeitet vor dem Pull Request geöffnet werden. Dies ist ein wichtiger Schritt um die Diksussion mit der Community bzgl. der Änderungen zu beginnen. Mit einem Issue wird es ermöglicht die Idee zu besprechen und zu erörtern wie entsprechender Code implementiert werden muss. Des Weiteren kann so die Community erfahren an was man gerade arbeitet, ob Hilfe benötigt wird, und zusätzlich kann man auf das Issue in Diskussionen referenzieren.

Falls Code geschrieben wurde und man Hilfe benötigt diesen fertig zu stellen, man Feedback vor der Fertigstellung erwünscht, oder den Code vor der Implementierung diskutieren möchte, so kann man einen „Work In Progress“ Pull-Request eröffnen. Wenn man einen Pull-Request erstellt, muss dem Titel der Tag [WIP] (Work In Progress) vorangestellt werden. Dies gibt an, dass der Code im Pull-Request nicht final ist und sich ändern wird. Des Weiteren wird der entsprechende Commit nicht übernommen („merged“) bis die Änderung final ist. Der [WIP] Tag kann von einem selbst oder einem Reviewer entfernt werden, sobald der Code fertig ist und die Änderung übernommen werden kann („merged“).

Code-Review¶

Ein Code-Review ist öffentlich und kann von jedem ausgeführt werden. Nur „Maintainer“ haben Zugriff zu Merge-Commits, jedoch ist das Feedback der Community zu Pull-Requests sehr nützlich. Es hilft zusätzlich mehr über den Code zu lernen. Die Liste aller offenen Pull-Requests findet sich hier:

Element	Pull-Requests
qiskit-terra	https://github.com/Qiskit/qiskit-terra/pulls
qiskit-aer	https://github.com/Qiskit/qiskit-aer/pulls
qiskit-ignis	https://github.com/Qiskit/qiskit-ignis/pulls
qiskit-aqua	https://github.com/Qiskit/qiskit-aqua/pulls
Dokumente oder Qiskit Meta-Pakete	https://github.com/Qiskit/qiskit/pulls

Commit-Nachricht¶

Der Inhalt einer Commit-Nachricht beschreibt die Änderung und ist genauso wichtig wie die Änderung selbst. Die Commit-Nachricht liefert den Kontext nicht nur für den Code-Review, sondern auch für den Verlauf der Änderungen im Git-Log. Eine detaillierte Commit-Nachricht erleichtert den Code-Review und liefert den Kontext, falls jemand die Änderung in der Zukunft nachvollziehen möchte. Für eine Commit-Nachricht sollten folgende Dinge beachtet werden:

Man sollte nicht annehmen, dass der Reviewer versteht, was das ursprüngliche Problem war.

Wenn man ein Issue und eine Reihe von Kommentaren und Antworten darauf liest, ist die Ursache des Problems in der Regel schnell klar. Die Commit-Nachricht sollte klar stellen was das ursprüngliche Problem ist. Im Falle eines Bugs ist es prinzipiell wichtig zu wissen, wie das Problem festgestellt wurde. Es sollte mittels der Commit-Nachricht möglich sein einen Patch auf Korrektheit zu überprüfen, ohne vorher das Bug Ticket zu lesen.

Gehen Sie nicht davon aus, dass der Code selbsterklärend/selbstdokumentierend ist.

Was für eine Person selbsterklärend ist, ist möglicherweise nicht verständlich für jemand anders. Man sollte immer dokumentieren, was das ursprüngliche Problem war und wie man es löst. Dies gilt für jede Änderung mit Ausnahme von offensichtlichen Tippfehlern.

Beschreiben Sie, warum eine Änderung vorgenommen wird.

Ein verbreiteter Fehler ist es nur zu dokumentieren wie ein Code geschrieben wurde, ohne zu erklären warum der Entwickler den Code so geschrieben hat. Natürlich sollte die Code-Struktur beschrieben werden; dies gilt insbesondere bei größeren Änderungen. Jedoch sollte man ebenso die Motivation für die Änderungen dokumentieren.

Lesen Sie die Commit-Nachricht, um zu sehen, ob sie Hinweise auf eine verbesserte Codestruktur liefert.

Bei grösseren Commit-Nachrichten wird es oft deutlich, dass ein Commit in mehrere Teile hätte aufgeteilt werden sollen. Man sollte nicht davor zurück schrecken die Änderung entsprechend anzupassen und in mehrere Pull-Requests zu splitten.

Bevor man ein Review durchführt sollte sichergestellt werden, dass genügend Informationen vorliegen.

Wenn GitHub eine Email bzgl. eines neuen Pull-Requests versendet, ist darin nur minimale Information enthalten - in der Regel die Commit-Nachricht und eine Liste der Dateien, die von einer Änderung betroffen sind. Aufgrund der hohen Patchanzahl, muss eine Commit-Nachricht ausreichend Informationen für potentielle Reviewer enthalten.

Die erste Commit-Zeile ist am wichtigsten.

In Git-Commits hat die erste Zeile der Commit-Nachricht eine besondere Bedeutung. Sie wird als Standardtitel für Pull-Request, Betreffzeile von E-Mail-Benachrichtigungen, Annotationsnachrichten in Git, gitk-Viewer-Anmerkungen, Merge-Commit-Nachrichten und an vielen weiteren Stellen verwendet, in denen es auf Platz ankommt. Neben der Zusammenfassung der Änderung selbst sollte es genau mitteilen, welche Teile des Codes betroffen sind.

Darüber hinaus wird die erste Zeile der Commit-Nachricht der Eintrag im generierten Changelog, sobald der PR im Changelog als hinzugefügt markiert ist. Es ist von entscheidender Bedeutung, dass Sie klare und prägnante zusammenfassende Zeilen verfassen.

Beschreiben Sie alle Einschränkungen des aktuellen Codes.

Wenn der Code, an dem man gearbeitet hat, noch Spielraum für künftige Verbesserungen lässt oder bestimmte Einschränkungen hat, sollte man das in seiner Commit-Nachricht vermerken. Dies zeigt dem Reviewer, dass das Problem umfassend betrachtet wurde und welche Kompromisse zugunsten kurzfristiger Zielen gegenüber langfristiger Absichten eingegangen wurden.

Referenzen zu Issues hinzufügen.

If the commit fixes are related to an issue, make sure you annotate that in the commit message. Use the syntax:

Fixes #1234

if it fixes the issue (GitHub will close the issue when the PR merges).

The main rule to follow is:

The commit message must contain all the information required to fully understand and review the patch for correctness. Less is not more.

Documenting Your Code¶

If you make a change to an element, make sure you update the associated docstrings and parts of the documentation under docs/apidocs in the corresponding repo. To locally build the element-specific documentation, run tox -edocs to compile and build the documentation locally and save the output to docs/_build/html. Additionally, the Docs CI job on azure pipelines will run this and host a zip file of the output that you can download and view locally.

If you have an issue with the combined documentation that is maintained in the Qiskit/qiskit repo, you can open a documentation issue if you see doc bugs, have a new feature that needs to be documented, or think that material could be added to the existing docs.

Good First Contributions¶

If you would like to contribute to Qiskit, but aren’t sure where to get started, the good first issue label on issues for a project highlights items appropriate for people new to the project. These are all issues that have been reviewed and tagged by contributors as something a new contributor should be able to work on. In other words, intimate familiarity with Qiskit is not a requirement to develop a fix for the issue.

Deprecation Policy¶

Qiskit users need to know if a feature or an API they rely upon will continue to be supported by the software tomorrow. Knowing under which conditions the project can remove (or change in a backwards-incompatible manner) a feature or API is important to the user. To manage expectations, the following policy is how API and feature deprecation/removal is handled by Qiskit:

1. Features, APIs, or configuration options are marked deprecated in the code. Appropriate DeprecationWarning class warnings will be sent to the user. The deprecated code will be frozen and receive only minimal maintenance (just so that it continues to work as-is).

2. A migration path will be documented for current users of the feature. This will be outlined in the both the release notes adding the deprecation, and the release notes removing the feature at the completion of the deprecation cycle. If feasible, the warning message will also include the migration path. A migration path might be „stop using that feature“, but in such cases it is necessary to first judge how widely used and/or important the feature is to users, in order to determine a reasonable obsolescence date.

3. An obsolescence date for the feature will be set. The feature must remain intact and working (although with the proper warning being emitted) in all releases pushed until after that obsolescence date. At the very minimum, the feature (or API, or configuration option) should be marked as deprecated (and continue to be supported) for at least three months of linear time from the release date of the first release to include the deprecation warning. For example, if a feature were deprecated in the 0.9.0 release of Terra, which was released on August 22, 2019, then that feature should still appear in all releases until at least November 22, 2019. Since releases do not occur at fixed time intervals, a deprecation warning may only occur in one release prior to removal.

Note that this delay is a minimum. For significant features, it is recommended that the deprecated feature appears for at least double that time. Also, per the stable branch policy, deprecation removals can only occur during minor version releases; they are not appropriate for backporting.

Deprecation Warnings¶

The proper way to raise a deprecation warning is to use the warn function from the warnings module in the Python standard library. The warning category class should be a DeprecationWarning. An example would be:

import warnings

def foo(input):
    warnings.warn('The qiskit.foo() function is deprecated as of 0.9.0, and '
                  'will be removed no earlier than 3 months after that '
                  'release date. You should use the qiskit.bar() function '
                  'instead.', DeprecationWarning, stacklevel=2)

One thing to note here is the stack_level kwarg on the warn() call. This argument is used to specify which level in the call stack will be used as the line initiating the warning. Typically, stack_level should be set to 2, as this will show the line calling the context where the warning was raised. In the above example, it would be the caller of foo(). If you did not set this, the warning would show that it was caused by the line in the foo() function, which is not helpful for users trying to determine the origin of a deprecated call. However, this value may be adjusted, depending on the call stack and where warn() gets called from. For example, if the warning is always raised by a private method that only has one caller, stack_level=3 might be appropriate.

Stable Branch Policy¶

The stable branch is intended to be a safe source of fixes for high-impact bugs and security issues that have been fixed on master since a release. When reviewing a stable branch PR, we must balance the risk of any given patch with the value that it will provide to users of the stable branch. Only a limited class of changes are appropriate for inclusion on the stable branch. A large, risky patch for a major issue might make sense, as might a trivial fix for a fairly obscure error-handling case. A number of factors must be weighed when considering a change:

The risk of regression: even the tiniest changes carry some risk of breaking something, and we really want to avoid regressions on the stable branch.
The user visibility benefit: are we fixing something that users might actually notice, and if so, how important is it?
How self-contained the fix is: if it fixes a significant issue but also refactors a lot of code, it’s probably worth thinking about what a less risky fix might look like.
Whether the fix is already on master: a change must be a backport of a change already merged onto master, unless the change simply does not make sense on master.

Backporting procedure:¶

When backporting a patch from master to stable, we want to keep a reference to the change on master. When you create the branch for the stable PR, use:

$ git cherry-pick -x $master_commit_id

However, this only works for small self-contained patches from master. If you need to backport a subset of a larger commit (from a squashed PR, for example) from master, do this manually. In these cases, add:

Backported from: #master pr number

so that we can track the source of the change subset, even if a strict cherry-pick doesn't make sense.

If the patch you’re proposing will not cherry-pick cleanly, you can help by resolving the conflicts yourself and proposing the resulting patch. Please keep Conflicts lines in the commit message to help review of the stable patch.

Backport labels¶

Bugs or PRs tagged with stable backport potential are bugs that apply to the stable release too and may be suitable for backporting once a fix lands in master. Once the backport has been proposed, the tag should be removed.

Include [Stable] in the title of the PR against the stable branch, as a sign that setting the target branch as stable was not a mistake. Also, reference to the PR number in master that you are porting.

Contributing to Documentation¶

Qiskit documentation is shaped by the docs as code philosophy, primarily drawn from Qiskit code comments in the style of API documentation.

The documentation is built from the master branch of Qiskit/qiskit/docs using Sphinx. The majority of documentation, under API Reference, is drawn from code comments in the repositories listed in Wo sich die Qiskit-Bestandteile befinden.

Documentation Structure¶

The way documentation is structured in Qiskit is to push as much of the actual documentation into the docstrings as possible. This makes it easier for additions and corrections to be made during development, because the majority of the documentation lives near the code being changed. There are three levels in the normal documentation structure in Terra:

The .rst files in the docs/apidocs

These files are used to tell Sphinx which modules to include in the rendered documentation. This contains two pieces of information: an internal reference or cross reference to the module, which can be used for internal links inside the documentation, and an automodule directive used to parse the module docstrings from a specified import path. For example, the dagcircuit.rst file contains:

.. _qiskit-dagcircuit:


.. automodule:: qiskit.dagcircuit
   :no-members:
   :no-inherited-members:
   :no-special-members:

The only .rst file outside of this is qiskit.rst, which contains the table of contents. If you’re adding a new .rst file for a new module’s documentation, make sure to add it to the toctree in that file.

The module-level docstring

This docstring is at the module level for the module specified in the automodule directive in the rst file. If the module specified is a directory/namespace, the docstring should be specified in the __init__.py file for that directory. This module-level docstring contains more details about the module being documented. The normal structure to this docstring is to outline all the classes and functions of the public API that are contained in that module. This is typically done using the autosummary directive (or autodoc directives directly if the module is simple, such as in the case of qiskit.execute). The autosummary directive is used to autodoc a list of different Python elements (classes, functions, etc.) directly without having to manually call out the autodoc directives for each one. The module-level docstring is where to provide a high-level overview of what functionality the module provides. This is normally done by grouping the different components of the public API together into multiple subsections.

For example, as in the previous dagcircuit module example, the contents of the module docstring for qiskit/dagcircuit/__init__.py would be:

"""
=======================================
DAG Circuits (:mod:`qiskit.dagcircuit`)
=======================================
.. currentmodule:: qiskit.dagcircuit
DAG Circuits
============
.. autosummary::
   :toctree: ../stubs/
   DAGCircuit
   DAGNode
Exceptions
==========
.. autosummary::
   :toctree: ../stubs/
   DAGCircuitError
"""

Bemerkung

This is just an example and the actual module docstring for the dagcircuit module might diverge from this.

The actual docstring for the elements listed in the module docstring

You should strive to document thoroughly all the public interfaces exposed using examples when necessary. For docstrings, Google Python Style Docstrings are used. This is parsed using the napoleon sphinx extension. The napoleon documentation contains a good example of how docstrings should be formatted.

Bemerkung

You can use any Sphinx directive or rst formatting in a docstring as it makes sense. For example, one common extension used is the jupyter-execute directive, which is used to execute a code block in Jupyter and display both the code and output. This is particularly useful for visualizations.

Documentation Integration¶

The hosted documentation at https://qiskit.org/documentation/ covers the entire Qiskit project; Terra is just one component of that. As such, the documentation builds for the hosted version are built by the Qiskit meta-package repository https://github.com/Qiskit/qiskit. When commits are merged to that repo, the output of Sphinx builds are uploaded to the qiskit.org website. Those Sphinx builds are configured to pull in the documentation from the version of the Qiskit elements installed by the meta-package at that point. For example, if the meta-package version is currently 0.13.0, then that will copy the documentation from Terra’s 0.10.0 release. When the meta-package’s requirements are bumped, then it will start pulling documentation from the new version. This means that fixes for incorrect API documentation will need to be included in a new release. Documentation fixes are valid backports for a stable patch release per the stable branch policy (see that section below).

During the build process, the contents of each element’s docs/apidocs/ are recursively copied into a shared copy of doc/apidocs/ in the meta-package repository along with all the other elements. This means that what is in the root of docs/apidocs on each element at a release will end up on the root of https://qiskit.org/documentation/apidoc/.

Translating Documentation¶

Qiskit documentation is translated (localized) using Crowdin, a software and web localization platform that allows organizations to coordinate translation projects and collaborate with communities to translate materials. Crowdin allows our community of translators to amplify their impact by automatically reusing the work invested translating one sentence to translate other, similar sentences. Crowdin also makes translations resilient to many types of changes to the original material, such as moving sentences around, even across files.

Qiskit localization requests are handled in Qiskit Translations repository. To contribute to Qiskit localization, please follow these steps:

Add your name (or ID) to the LOCALIZATION_CONTRIBUTORS file.
Create a pull request (PR) to merge your change. Make sure to follow the template to open a Pull Request.
Bemerkung
- Each contributor has to create their own PR and sign the CLA.
- Please mention the language that you’d like to contribute to in the PR summary.
- If you have an open issue for a language request, add the issue link to the PR.
You will be asked to sign the Qiskit Contributors License Agreement (CLA); please do so.
A minimum of three contributors per language are necessary for any new languages to be added, to receive official support from the administrators of the localization project.
Among the group of contributors, a translation lead must be identified to serve as a liaison with the administrators of the localization project. The lead must contact: Yuri Kobayashi (yurik@jp.ibm.com) by email.
In the Qiskit-Docs Crowdin project, choose the language that you want to contribute to.

Bemerkung

As mentioned in the blog post, Qiskit in my language is Qiskit, we want to make sure that translated languages have enough community support to build a translation team with translators, proofreaders, and translation leads. If you want to be a translation lead or would be willing to join a new translation project team, you can open a GitHub issue to start a discussion with the Qiskit team and recruit translation project members.
Click the Join button and paste the URL of your PR in the dialog box where you are asked why you want to join the Crowdin project.

The administrators of the Crowdin project will review your request and give you access as quickly as they can.

Building from Source¶

You can build a local copy of the documentation from your local clone of the Qiskit/qiskit repository as follows:

Clone the Qiskit repository.

git clone https://github.com/Qiskit/qiskit.git

Cloning the repository creates a local folder called qiskit.
```
cd qiskit
```
Build the documentation by navigating to your local clone of Qiskit/qiskit and running the following command in a terminal window.
```
tox -edocs
```
If you do not already have the tox command installed, install it by running:
```
pip install tox
```

As you make changes to your local RST files, you can update your HTML files by navigating to /doc/ and running the following in a terminal window:

tox -edocs

This will build a styled, HTML version of your local documentation repository in the subdirectory /docs/_build/html/.

Installing from Source¶

Installing the elements from source allows you to access the most recently updated version of Qiskit instead of using the version in the Python Package Index (PyPI) repository. This will give you the ability to inspect and extend the latest version of the Qiskit code more efficiently.

When installing the elements and components from source, by default their development version (which corresponds to the master git branch) will be used, as opposed to the stable version (which contains the same codebase as the published pip packages). Since the development versions of an element or component usually include new features and changes, they generally require using the development version of the rest of the items as well.

Bemerkung

The Terra and Aer packages both require a compiler to build from source before you can install. Ignis, Aqua, and the IBM Quantum Provider backend do not require a compiler.

Installing elements from source requires the following order of installation to prevent installing versions of elements that may be lower than those desired if the pip version is behind the source versions:

qiskit-terra
qiskit-aer
qiskit-ignis
qiskit-aqua
qiskit-ibmq-provider (if you want to connect to the IBM Quantum devices or online simulator)

To work with several components and elements simultaneously, use the following steps for each element.

Bemerkung

Due to the use of namespace packaging in Python, care must be taken in how you install packages. If you’re planning to install any element from source, do not use the qiskit meta-package. Also, follow this guide and use a separate virtual environment for development. If you do choose to mix an existing installation with your development, refer to https://github.com/pypa/sample-namespace-packages/blob/master/table.md for the set of combinations of installation methods that work together.

Set up the Virtual Development Environment¶

Virtual environments are used for Qiskit development to isolate the development environment from system-wide packages. This way, we avoid inadvertently becoming dependent on a particular system configuration. For developers, this also makes it easy to maintain multiple environments (e.g. one per supported Python version, for older versions of Qiskit, etc.).

Bemerkung

M1 Mac users: Some Qiskit dependencies may not yet be available in PyPI. Until they are, Conda is recommended.

Python venv

All Python versions supported by Qiskit include built-in virtual environment module venv.

Start by creating a new virtual environment with venv. The resulting environment will use the same version of Python that created it and will not inherit installed system-wide packages by default. The specified folder will be created and is used to hold the environment’s installation. It can be placed anywhere. For more detail, see the official Python documentation, Creation of virtual environments.

python3 -m venv ~/.venvs/qiskit-dev

Activate the environment by invoking the appropriate activation script for your system, which can be found within the environment folder. For example, for bash/zsh:

source ~/.venvs/qiskit-dev/bin/activate

Upgrade pip within the environment to ensure Qiskit dependencies installed in the subsequent sections can be located for your system.

pip install -U pip

Conda

For Conda users, a new environment can be created as follows.

conda create -y -n QiskitDevenv python=3
conda activate QiskitDevenv

Installing Terra from Source¶

Installing from source requires that you have a C++ compiler on your system that supports C++11.

Compiler for Linux

On most Linux platforms, the necessary GCC compiler is already installed.

Compiler for macOS

If you use macOS, you can install the Clang compiler by installing XCode. Check if you have XCode and Clang installed by opening a terminal window and entering the following.

clang --version

Install XCode and Clang by using the following command.

xcode-select --install

Compiler for Windows

On Windows, it is easiest to install the Visual C++ compiler from the Build Tools for Visual Studio 2017. You can instead install Visual Studio version 2015 or 2017, making sure to select the options for installing the C++ compiler.

Once the compilers are installed, you are ready to install Qiskit Terra.

Clone the Terra repository.

git clone https://github.com/Qiskit/qiskit-terra.git

Cloning the repository creates a local folder called qiskit-terra.
```
cd qiskit-terra
```
Install the Python requirements libraries from your qiskit-terra directory.
```
pip install cython
```
If you want to run tests or linting checks, install the developer requirements.
```
pip install -r requirements-dev.txt
```
Install qiskit-terra.
```
pip install .
```

If you want to install it in editable mode, meaning that code changes to the project don’t require a reinstall to be applied, you can do this with:

pip install -e .

You can then run the code examples after installing Terra. You can run the example with the following command.

python examples/python/using_qiskit_terra_level_0.py

Bemerkung

If you do not intend to install any other components, qiskit-terra will emit a RuntimeWarning warning that both qiskit-aer and qiskit-ibmq-provider are not installed. This is done because users commonly intend to use the additional elements, but do not realize they are not installed, or that the installation of either Aer or the IBM Quantum Provider failed for some reason. If you wish to suppress these warnings, add:

import warnings
warnings.filterwarnings('ignore', category=RuntimeWarning,
                        module='qiskit')

before any qiskit imports in your code. This will suppress the warning about the missing qiskit-aer and qiskit-ibmq-provider, but will continue to display any other warnings from qiskit or other packages.

Installing Aer from Source¶

Clone the Aer repository.

git clone https://github.com/Qiskit/qiskit-aer

Install build requirements.
```
pip install cmake scikit-build cython
```

After this, the steps to install Aer depend on which operating system you are using. Since Aer is a compiled C++ program with a Python interface, there are non-Python dependencies for building the Aer binary which can’t be installed universally depending on operating system.

Linux

Install compiler requirements.

Building Aer requires a C++ compiler and development headers.

If you’re using Fedora or an equivalent Linux distribution, install using:
```
dnf install @development-tools
```
For Ubuntu/Debian install it using:
```
apt-get install build-essential
```
Install OpenBLAS development headers.

If you’re using Fedora or an equivalent Linux distribution, install using:
```
dnf install openblas-devel
```
For Ubuntu/Debian install it using:
```
apt-get install libopenblas-dev
```

macOS

Bemerkung

Mac M1 Users: There are ongoing issues with building Aer for AArch64 macOS. See #1286 for discussion and workarounds before continuing.

Install dependencies.

To use the Clang compiler on macOS, you need to install an extra library for supporting OpenMP. You can use brew to install this and other dependencies.
```
brew install libomp
```
Then install a BLAS implementation; OpenBLAS is the default choice.
```
brew install openblas
```
Next, install Xcode Command Line Tools.
```
xcode-select --install
```

Windows

On Windows you need to use Anaconda3 or Miniconda3 to install all the dependencies.

Install compiler requirements.

conda install --update-deps vs2017_win-64 vs2017_win-32 msvc_runtime

Install binary and build dependencies.

conda install --update-deps -c conda-forge -y openblas cmake

Build and install qiskit-aer directly

If you have pip <19.0.0 installed and your environment doesn’t require a custom build, run:
```
cd qiskit-aer
pip install .
```
This will both build the binaries and install Aer.

Alternatively, if you have a newer pip installed, or have some custom requirement, you can build a Python wheel manually.
```
cd qiskit-aer
python ./setup.py bdist_wheel
```
If you need to set a custom option during the wheel build, refer to Custom options during wheel builds.

After you build the Python wheel, it will be stored in the dist/ dir in the Aer repository. The exact version will depend
```
cd dist
pip install qiskit_aer-*.whl
```
The exact filename of the output wheel file depends on the current version of Aer under development.

Custom options during wheel builds¶

The Aer build system uses scikit-build to run the compilation when building it with the Python interface. It acts as an interface for setuptools to call CMake and compile the binaries for your local system.

Due to the complexity of compiling the binaries, you may need to pass options to a certain part of the build process. The way to pass variables is:

python setup.py bdist_wheel [skbuild_opts] [-- [cmake_opts] [-- build_tool_opts]]

where the elements within square brackets [] are optional, and skbuild_opts, cmake_opts, build_tool_opts are to be replaced by flags of your choice. A list of CMake options is available here: https://cmake.org/cmake/help/v3.6/manual/cmake.1.html#options. For example, you could run something like:

python setup.py bdist_wheel -- -- -j8

This is passing the flag -j8 to the underlying build system (which in this case is Automake), telling it that you want to build in parallel using 8 processes.

For example, a common use case for these flags on linux is to specify a specific version of the C++ compiler to use (normally if the default is too old):

python setup.py bdist_wheel -- -DCMAKE_CXX_COMPILER=g++-7

which will tell CMake to use the g++-7 command instead of the default g++ when compiling Aer.

Another common use case for this, depending on your environment, is that you may need to specify your platform name and turn off static linking.

python setup.py bdist_wheel --plat-name macosx-10.9-x86_64 \
-- -DSTATIC_LINKING=False -- -j8

Here --plat-name is a flag to setuptools, to specify the platform name to use in the package metadata, -DSTATIC_LINKING is a flag for using CMake to disable static linking, and -j8 is a flag for using Automake to use 8 processes for compilation.

A list of common options depending on platform are:

Platform	Tool	Option	Use Case
All	Automake	-j	Followed by a number, sets the number of processes to use for compilation.
Linux	CMake	-DCMAKE_CXX_COMPILER	Used to specify a specific C++ compiler; this is often needed if your default g++ is too old.
OSX	setuptools	–plat-name	Used to specify the platform name in the output Python package.
OSX	CMake	-DSTATIC_LINKING	Used to specify whether or not static linking should be used.

Bemerkung

Some of these options are not platform-specific. These particular platforms are listed because they are commonly used in the environment. Refer to the tool documentation for more information.

Installing Ignis from Source¶

Clone the Ignis repository.

git clone https://github.com/Qiskit/qiskit-ignis.git

Cloning the repository creates a local directory called qiskit-ignis.
```
cd qiskit-ignis
```
If you want to run tests or linting checks, install the developer requirements. This is not required to install or use the qiskit-ignis package when installing from source.
```
pip install -r requirements-dev.txt
```
Install Ignis.
```
pip install .
```

If you want to install it in editable mode, meaning that code changes to the project don’t require a reinstall to be applied:

pip install -e .

Installing Aqua from Source¶

Clone the Aqua repository.

git clone https://github.com/Qiskit/qiskit-aqua.git

Cloning the repository creates a local directory called qiskit-aqua.
```
cd qiskit-aqua
```
If you want to run tests or linting checks, install the developer requirements. This is not required to install or use the qiskit-aqua package when installing from source.
```
pip install -r requirements-dev.txt
```
Install Aqua.
```
pip install .
```

If you want to install it in editable mode, meaning that code changes to the project don’t require a reinstall to be applied:

pip install -e .

Installing IBM Quantum Provider from Source¶

Clone the qiskit-ibmq-provider repository.

git clone https://github.com/Qiskit/qiskit-ibmq-provider.git

Cloning the repository creates a local directory called qiskit-ibmq-provider.
```
cd qiskit-ibmq-provider
```
If you want to run tests or linting checks, install the developer requirements. This is not required to install or use the qiskit-ibmq-provider package when installing from source.
```
pip install -r requirements-dev.txt
```
Install qiskit-ibmq-provider.
```
pip install .
```

If you want to install it in editable mode, meaning that code changes to the project don’t require a reinstall to be applied:

pip install -e .

Qiskit Versioning¶

The Qiskit project is made up of several elements each performing different functionality. Each is independently useful and can be used on their own, but for convenience we provide this repository and meta-package to provide a single entrypoint to install all the elements at once. This is to simplify the install process and provide a unified interface to end users. However, because each Qiskit element has it’s own releases and versions some care is needed when dealing with versions between the different repositories. This document outlines the guidelines for dealing with versions and releases of both Qiskit elements and the meta-package.

For the rest of this guide the standard Semantic Versioning nomenclature will be used of: Major.Minor.Patch to refer to the different components of a version number. For example, if the version number was 0.7.1, then the major version is 0, the minor version 7, and the patch version 1.

Meta-package Version¶

The Qiskit meta-package version is an independent value that is determined by the releases of each of the elements being tracked. Each time we push a release to a tracked component (or add an element) the meta-package requirements, and version will need to be updated and a new release published. The timing should be coordinated with the release of elements to ensure that the meta-package releases track with element releases.

Adding New Tracked Elements¶

When a new Qiskit element is being added to the meta-package requirements, we need to increase the Minor version of the meta-package.

For example, if the meta-package is tracking 2 elements qiskit-aer and qiskit-terra and it’s version is 0.7.4. Then we release a new element qiskit-ignis that we intend to also have included in the meta-package. When we add the new element to the meta-package we increase the version to 0.8.0.

Patch Version Increases¶

When any Qiskit element that is being already tracked by the meta-package releases a patch version to fix bugs in a release we need also bump the requirement in the setup.py and then increase the patch version of the meta-package.

For example, if the meta-package is tracking 3 elements qiskit-terra==0.8.1, qiskit-aer==0.2.1, and qiskit-ignis==0.1.4 with the current version 0.9.6. When qiskit-terra release a new patch version to fix a bug 0.8.2 the meta-package will also need to increase it’s patch version and release, becoming 0.9.7.

Additionally, there are occasionally packaging or other bugs in the meta-package itself that need to be fixed by pushing new releases. When those are encountered we should increase the patch version to differentiate it from the broken release. Do not delete the broken or any old releases from pypi in any situation, instead just increase the patch version and upload a new release.

Minor Version Increases¶

Besides adding a new element to the meta-package the minor version of the meta-package should also be increased anytime a minor version is increased in a tracked element.

For example, if the meta-package is tracking 2 elements qiskit-terra==0.7.0 and qiskit-aer==0.1.1 and the current version is 0.7.5. When the qiskit-aer element releases 0.2.0 then we need to increase the meta-package version to be 0.8.0 to correspond to the new release.

Major Version Increases¶

The major version is different from the other version number components. Unlike the other version number components, which are updated in lock step with each tracked element, the major version is only increased when all tracked versions are bumped (at least before 1.0.0). Right now all the elements still have a major version number component of 0 and until each tracked element in the meta-repository is marked as stable by bumping the major version to be >=1 then the meta-package version should not increase the major version.

The behavior of the major version number component tracking after when all the elements are at >=1.0.0 has not been decided yet.

Optional Extras¶

In addition to the tracked elements there are additional packages built on top of Qiskit which are developed in tandem with Qiskit for example the application repositories like qiskit-optimization. For convienence these packages are tracked by the Qiskit metapackage as optional extras that can be installed with Qiskit. Releases of these optional downstream projects do not trigger a metapackage release as they are unpinned and do not effect the metapackage version. If there is a compatibility issue between Qiskit and these downstream optional dependencies and the minimum version needs to be adjusted in a standalone release this will only be done as a patch version release as it’s a packaging bugfix.

Qiskit Element Requirement Tracking¶

While not strictly related to the meta-package and Qiskit versioning how we track the element versions in the meta-package’s requirements list is important. Each element listed in the setup.py should be pinned to a single version. This means that each version of Qiskit should only install a single version for each tracked element. For example, the requirements list at any given point should look something like:

requirements = [
    "qiskit_terra==0.7.0",
    "qiskit-aer==0.1.1",
]

This is to aid in debugging, but also make tracking the versions across multiple elements more transparent.