Qiskit に貢献する

Qiskit はどのようなバックグランドをもった人にも量子コンピューティングをもたらすことにコミットしたオープンソースプロジェクトです。このページでは、 Qiskit コミュニティーにどのように参加できるかを説明しています。

Qiskitのコードのロケーションについて

Qiskit のコードは Qiskit GitHub にあり、Qiskit を構成する以下の個別のプロジェクトを確認することが出来ます。

バグの報告と機能強化のリクエスト

問題を発見したら、適切な要素(e.g. Terra, Aqua, Aer, Ignis)の課題管理機能 issue trackerでissueをあげてください:

要素

課題管理

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

ドキュメントまたはQiskitメタパッケージ

https://github.com/Qiskit/qiskit/issues

新しい機能のアイデアがある場合は、該当する要素の課題管理機能 issue trackerで Enhancement issue を開いてください。 issue を開くと、チームとあなたのアイデア、プロジェクトとの適合性、実装方法などに関する議論が始まります。

コードの貢献

スタイルガイド

プロジェクト内のコーディング・スタイルの統一を図るため、Pylintpycodesytle を使用して、コードへの貢献がプロジェクトのスタイルガイドに準拠していることを確認しています。ご自身の変更がスタイルガイドを遵守しているか確認するには、tox -elint を実行してください。

Contributor License Agreement (CLA、貢献者ライセンス同意書)

実際にコードを提出する前に、貢献者はCLA (貢献者ライセンス同意書) への同意が必要です。CLAに同意することで、貢献内容の著作者であることを証明し、Apache-2.0 ライセンスの規約の下で貢献していることを意味します。

Qiskit プロジェクトへのプルリクエストを行う際、リクエストを挙げた人がCLAに同意済みか否かをbotが判定します。同意済みではない場合は、botが同意書へのリンクとともに対応を促すコメントを返しますので対応をお願いします。 CLA の内容はPDF形式で参照可能です。

注釈

あなたの貢献が業務の一環、または雇用主の所有物として位置づけられる場合は、 corporate CLA に署名をいただいて <qiskit@us.ibm.com>まで送っていただく必要があります。

プルリクエスト

コードへの貢献をアクセプトするため、GitHub pull requests を使用しています。

必須ではありませんが、プルリクエストを作成する前に修正中のバグや作業中の機能に関する新しいissueを作成することは、あなたの作業についてコミュニティと議論を始めるための重要なステップです。 このissueは、アイデアやコードでそれを実装するためにどのように協力できるかについて話す場を提供します。 また、コミュニティはあなたが取り組んでいるものを知ることができ、助けが必要な場合は、他のコミュニティやチームメンバーと議論するときにissueを参照できます。

書いているコードを完成させるために助けが必要だったり、完成前に初期的なフィードバックが欲しかったり、実装完了前に共有して議論したい場合、Work in Progress プルリクエストを作成することができます。プルリクエストを作成する時、[WIP] タグ (Work in Progressの意) をタイトルの先頭につけて下さい。これはレビューワーに対して、このPR (プルリクエスト) が最終状態ではなく、変更の可能性があることを明示します。また、完成するまでコミットがマージされないことも意味します。コードがマージ用にレビューされる準備ができた時、自分自身もしくはレビューワーが[WIP] タグを削除できます。

コードレビュー

コードレビューはオープンになされ、誰でも見ることができます。メンテナーだけがコミットをマージするアクセス権を持ちますが、プルリクエストへのコミュニティのフィードバックは本当に貴重です。また、コードベースについて学ぶ良い仕組みでもあります。オープン状態のプルリクエストのリストは以下から見ることができます:

要素

プルリクエスト

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

ドキュメントまたはQiskitメタパッケージ

https://github.com/Qiskit/qiskit/pulls

コミットメッセージ

変更を説明するコミットメッセージの内容は、変更自体と同じくらい重要です。 コミットメッセージは、コードレビューだけでなく、gitログの変更履歴の前後関係も提供します。 詳細なコミットメッセージによって、コードのレビューが容易になり、将来誰かが変更を確認したときに変更の背景も分かります。 コミットメッセージを書くときは、次の重要な詳細を覚えておいてください。

レビュアーがオリジナルの課題をきちんと理解していると思い込まないでください。

多くの前後のコメントの後にissueを読むと、しばしば根本的な原因の問題が何か明確になります。 コミットメッセージには、元の問題が何であるかを明確に記載する必要があります。 バグは、問題の特定方法に関する興味深い歴史的背景にすぎません。 バグチケットを読む必要なく、コミットメッセージから提案されたパッチの正確性をレビューすることが可能であるべきです。

コードが自明/自己文書化されていると想定しないでください。

ある人にとって自明なことは、他の人にとっては明らかではないかもしれません。 最も明白なタイプミスまたは空白のみのコミットを除くすべての変更について、元の問題が何であったか、どのように修正されているかを常に文書化します。

変更を行う理由を説明してください。

よくある間違いは、開発者がそのように選択した理由を説明せずに、コードの記述方法を文書化することだけです。 確かに、特に大規模な変更の場合は、全体的なコード構造を記述する必要がありますが、さらに重要なことは、変更の背後にある意図/動機を必ず記述してください。

コミットメッセージを読んで、コード構造の改善を示唆しているかどうかを確認します。

多くの場合、大きなコミットメッセージを記述するとき、コミットが2つ以上の部分に分割されるべきであることが明らかになります。 戻って変更をリベースし、それを個別のプルリクエストに分割することを恐れないでください。

レビューするかどうかを決定するのに十分な情報を確保します。

Githubが新しいプルリクエストに対して送信するメールアラートには、最小限の情報しか含まれません。通常は、コミットメッセージと更新ファイルのリストだけです。 パッチの量が多いため、コミットメッセージにはレビュー担当者がレビューする必要のあるパッチを見つけるのに十分な情報が含まれている必要があります。

最初のコミット行が最も重要です。

Gitコミットでは、コミットメッセージの最初の行に特別な意味があります。 デフォルトのプルリクエストタイトル、電子メール通知の件名、gitアノテーションメッセージ、gitkビューアーアノテーション、マージコミットメッセージ、およびスペースが貴重なその他の多くの場所として使用されます。 変更自体を要約するだけでなく、コードのどの部分が影響を受けるかを詳細に注意する必要があります。

さらに、PRが変更ログに含まれているとタグ付けされている場合、コミットメッセージの最初の行は、生成された変更ログのエントリになります。 明確で簡潔な要約行を書くことが非常に重要です。

現在のコードの制約を説明します。

変更中のコードに、将来的な改善の余地や既知の制限がある場合には、それらについてコミットメッセージで触れてください。そうすることで、レビューアに対して、より大局的な視点が考慮されていること、長期的な展望に対して短期的目標の観点からどのようなトレードオフが行われたかを示すことになります。

Issueへの参照を含めてください。

コミットする修正がIssueに関係している場合は、コミットメッセージでそのことを忘れずに注釈してください。次の構文を使用してください。

Fixes #1234

問題が修正された場合(PRがマージされるとGitHubは問題をクローズします)。

守るべき主なルールは次の通りです。

コミットメッセージには、パッチの正確性を完全に理解して確認するために必要なすべての情報が含まれている必要があります。この場合」Less is more(『より少なきは、より多きこと』)」にはなりません。

コードの文書化

要素に変更を加える場合、関連する * docstrings* と、対応するリポジトリの docs/ apidocs の下にあるドキュメントの一部を必ず更新してください。 要素固有のドキュメントをローカルでビルドするには、tox -edocs を実行してドキュメントをコンパイルしてローカルにビルドし、出力を docs / _build / html に保存します。 さらに、azureパイプラインのDocs CIジョブはこれを実行し、ダウンロードしてローカルで表示できる出力のzipファイルをホストします。

Qiskit/qiskit repo でメンテナンスされている combined documentation に問題がある場合、つまりドキュメントに間違いがあったり、ドキュメントすべき新機能があったり、既存のドキュメントに資料を追加できるような場合には、documentation issue を起こすことができます。

上手な最初の貢献

Qiskit に貢献したいけれどもどこから始めたらよいかわからない、というときは、プロジェクトについている good first issue というラベルがプロジェクトへの新規参加者にとって適していることを示します。これらのイシューはすべて、新しい貢献者が作業することができるものとして、貢献者によってレビューされタグ付けされたものです。言い換えると、イシューの解決を進めるのに、Qiskit によく精通していることが要求されるわけではありません。

非推奨に関する方針

Qiskit ユーザは、自分が依存している機能やAPIが将来のソフトウェアでも引き続きサポートされるかどうかを知る必要があります。どのような条件のもとで、プロジェクトが機能やAPIを削除(または後方互換性がないようなやり方で変更)してよいとしているかを知ることは、ユーザにとって重要です。Qiskit は期待を管理するため、以下のポリシーにしたがって、APIおよび機能の廃止/削除を扱っています。

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.

この遅延は最小値であることに注意してください。 重要な機能については、非推奨の機能であると少なくとも 2 回は表示されることを推奨します。 また、ブランチの安定化ポリシーによって、非推奨の削除は、マイナー・バージョンのリリース中にのみ発生することがあります。これらはバックポーティングには不適です。

非推奨の警告

非推奨の警告を出すのに適切な方法は、 Python 標準ライブラリの`warnings module <https://docs.python.org/3/library/warnings.html>`__ から``warn`` 機能を使用することです。 警告カテゴリー・クラスは DeprecationWarning でなければなりません。例として、次のようなものがあります:

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)

ここで注目すべき点は、 warn() メソッドの stack_level kwarg です。 この引数は、呼び出しスタック内のどのレベルが、警告を開始する行として使用されるかを指定するために使用されます。 通常、stack_level は 2に設定する必要があります。これにより、警告が出されたコンテキストを呼び出す行が表示されます。 上記の例では、foo()``の呼び出し元になります。これを設定しなかった場合は、 foo() 関数内の行で発生したと警告が表示されます。これは、非推奨の呼び出しの起点を判別しようとしているユーザーにとっては役に立ちません。 ただし、この値は、コール・スタックや ``warn() が呼び出される場所によって調整されることがあります。 例えば、警告が常に 1 つの呼び出し元のみを持つ private メソッドによって生成される場合は、 stack_level=3 が適切である場合があります。

ブランチの安定化ポリシー

Stableブランチは、リリース後にマスター上で修正された、影響の大きいバグやセキュリティー問題に対応する修正の安全なソースになることを目的としています。 安定ブランチのプルリクエスト(PR) をレビューする時、与えられたパッチのリスクと安定ブランチを提供する価値のバランスを取る必要があります。 安定したブランチへ組み込むには、限定されたクラスのみへの変更が適しています。 大きな問題に対する大きくリスクの高いパッチは、あまり目立たないのエラー処理のための些細な修正同様、理にかなっているかもしれません。 変更をレビューする際には、多くの要因を検討する必要があります。

  • リグレッションのリスク: 最も小さな変更でも何かを壊すリスクがあり、stableブランチ上でのリグレッションは本当に避けたいです。

  • ユーザーに見える利益: ユーザーが本当に気が付く修正していますか?そうであれば、その重要性はどのくらいですか?

  • 修正の自己完結度: 重要な問題を修正するだけでなく多くのコードをリファクタリングしている場合は、リスクの低い修正がどのようなものになるかを検討する価値があると考えられます。

  • 修正がすでにマスターブランチにあるかどうか: 変更がマスターに対して意味を持っていない場合、変更は既にマスターにマージされた変更のバックポートでなければなりません。

バックポーティングの方法

マスターから安定ブランチへパッチをバックポーティングする際には、マスター上の変更の参照を保持します。 安定したプルリクエスト(PR) のブランチを作成する場合、以下を使用して下さい:

$ git cherry-pick -x $master_commit_id

ただし、これはマスターからの小さな自己完結型パッチのみに対応しています。 マスターから、より大きなコミットのサブセット (例えば、squashされた PRなど) をバックポートする必要がある場合は、手動で行います。 このような場合には、以下を追加します:

Backported from: #master pr number

そうすれば、厳格なcherry-pickの意味が分からなくても、変更サブセットのソースを追跡できるようになります。

提案するパッチがきれいにcherry-pickしない場合は、競合を自分で解決し、その結果のパッチを提案することができます。 安定したパッチのレビューをサポートするために、コミット・メッセージ内の競合行を保持してください。

バックポート・ラベル

stable backport potential とタグ付けされたバグやプルリクエスト (PR) は、安定したリリースにも適用されるバグであり、マスターの一時修正が行われると、バックポーティングに適している可能性があります。 バックポートが提案されると、タグを削除する必要があります。

ターゲット・ブランチを安定と設定したことが間違いないようにするために、安定ブランチに対するプルリクエスト (PR) のタイトルに [Stable] を含めて下さい。また、ポーティングしているマスター中のプルリクエスト (PR) 番号を参照して下さい。

ドキュメンテーションへの貢献

Qiskit ドキュメンテーションは docs as code philosophy, に則り、 style of API documentation に基づくQiskitコードコメントから形成されています。

ドキュメントは、 Qiskit/qiskit/docs のmasterブランチから Sphinx を使用して構築されます 。API Reference の下にあるドキュメントの大部分は Qiskitのコードのロケーションについて にリストされているリポジトリのコードコメントから作成されています。

文書構造

Qiskitでドキュメントを構造化する方法は、できるだけ多くの実際のドキュメントをドキュメント文字列にプッシュすることです。 ドキュメントの大部分は変更されるコードの近くにあるため、これにより、開発中に追加や修正が簡単になります。 Terraの通常のドキュメント構造には3つのレベルがあります。

docs/apidocs の中の .rst ファイル

これらのファイルは、レンダリングされたドキュメントに含めるモジュールをSphinxに伝えるために使用されます。 これには、ドキュメント内の内部リンクに使用できるモジュールへの 内部参照 または 相互参照、および指定された挿入パスからモジュールのdocstringを解析するために使用される `自動モジュールディレクティブ <http://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>`__の2つの情報が含まれます。 たとえば、dagcircuit.rstファイルには以下が含まれます。

.. _qiskit-dagcircuit:


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

これ以外の唯一の .rst ファイルは qiskit.rst で、目次が含まれています。 新しいモジュールのドキュメント用に新しい .rst ファイルを追加する場合は、そのファイルの `toctree<https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#table-of-contents>`__ に必ず追加してください。

モジュール・レベルdocstring

このdocstringは、rstファイルの automodule ディレクティブで指定されたモジュールのモジュールレベルにあります。指定されたモジュールがディレクトリ/名前空間である場合、docstringはそのディレクトリの __init__.py ファイルで指定する必要があります。このモジュールレベルのdocstringには、ドキュメント化されるモジュールに関する詳細が含まれています。このdocstringの通常の構造は、そのモジュールに含まれているパブリックAPIのすべてのクラスと関数の概要を説明することです。これは通常、autosummary ディレクティブ を使用(または、qiskit.execute の場合のようにモジュールが単純な場合は autodoc ディレクティブ を直接使用)して行われます。 autosummaryディレクティブは、さまざまなPython要素(クラス、関数など)のリストを直接autodocするために使用されます。それぞれのautodocディレクティブを手動で呼び出す必要はありません。モジュールレベルのdocstringは、モジュールが提供する機能の概要を提供する場所です。これは通常、パブリックAPIのさまざまなコンポーネントを複数のサブセクションにグループ化することによって行われます

例えば、前のdagcircuitモジュールの例と同様に、qiskit/dagcircuit/__init__.py のdocstringモジュールの内容は次のようになります:

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

注釈

これは単なる例であり、dagcircuitモジュールの実際のdocstringモジュールはこれとは異なる場合があります。

docstringモジュールにリストされる要素の実際のdocstring

必要に応じて、例を使って公開されているすべてのパブリックインターフェイスを徹底的に文書化するように努める必要があります。 docstringsには、Google Python Style Docstrings が使用されます。 これは、 napoleon sphinx extension を使用してパースされます。 napoleon documentation には、docstringのフォーマット法の良い例が掲載されています。

注釈

理にかなっているように、docstringには、任意のSphinxディレクティブまたはrstフォーマットを使用できます。 例えば、一般的な拡張機能の1つに、Jupyterでコードブロックを実行し、コードと出力の両方を表示するために使用される jupyter-execute ディレクティブがあります。 これは特に視覚化に役立ちます。

ドキュメントの統合

https://qiskit.org/documentation/でホストされているドキュメントは、Qiskitプロジェクト全体をカバーしています; Terraはその1つのコンポーネントにすぎません。 そのため、ホストされたバージョンのドキュメントのビルドは、Qiskitのメタパッケージリポジトリー https://github.com/Qiskit/qiskit によってビルドされます。 コミットがそのリポジトリにマージされると、Sphinxビルドの出力がqiskit.orgのウェブサイトにアップロードされます。 これらのSphinxビルドは、その時点でメタパッケージによってインストールされたQiskit要素のバージョンからドキュメントを取り込むように構成されています。 例えば、メタパッケージのバージョンが現在0.13.0である場合、Terraの0.10.0リリースからドキュメントをコピーします。 メタパッケージから要求があると、新しいバージョンからドキュメントが取得され始めます。 これは、間違っているAPIドキュメントを修正して新しいリリースに含める必要があることを意味します。 ドキュメントの修正は、安定版ブランチポリシー(下記のセクションを参照)ごとに安定版パッチをリリースする有効なバックポートとなります。

ビルドプロセス中に、各要素の docs/apidocs/ のコンテンツは、他のすべての要素とともに、メタパッケージリポジトリー内の doc/apidocs/ の共有コピーに再帰的にコピーされます。 つまり、リリースの各要素のdocs/apidocsのルートにあるものは、最終的にはhttps://qiskit.org/documentation/apidoc/のルートになります。

ドキュメンテーションの翻訳について

Qiskitのドキュメントは、Crowdinを使用して翻訳(ローカライズ) されます。Crowdinは、組織が翻訳プロジェクトを調整し、コミュニティと協力して資料を翻訳できるようにするソフトウェアおよびWebローカリゼーションプラットフォームです。Crowdinを使用すると、翻訳者のコミュニティは、1つの文の翻訳に投資した作業を他の類似の文の翻訳に自動的に再利用することができます。また、Crowdinは、ファイル間での文の移動など、原文に対する多くの種類の変更に対して翻訳の復元力を高めます。

Qiskit ローカリゼーション リクエストは、Qiskit Translations リポジトリーで処理されます。 Qiskitのローカリゼーションに貢献するには、次の手順に従ってください:

  1. 名前またはIDを LOCALIZATION_CONTRIBUTORS ファイルに追加します。

  2. プルリクエスト (PR) を作成して、変更をマージします。 必ずテンプレートに従ってプルリクエストを開いてください。

    注釈

    • 貢献する人はそれぞれ、独自のPRを作成し、CLAに署名する必要があります。

    • PRのサマリーで、貢献する言語を記載してください。

    • 言語のリクエストでまだissueがopenのままの場合は、PRにそのissueのリンクを追加します

  3. Qiskit Contributors License Agreement(CLA)に署名するよう求められますので、 署名をお願い致します。

  4. 新しい言語を追加し、翻訳プロジェクトの管理者から公式なサポートを受けるためには、1言語につき 3人以上の貢献者 が必要です。

  5. 貢献者グループの中から、プロジェクト管理者と連携をとるリーダーのアサインをお願いします。リーダーはEメールにてyurik@jp.ibm.comまでご連絡ください。

  6. Qiskit-Docs Crowdinプロジェクトで、貢献したい言語を選択します。

    注釈

    Qiskit in my language is Qiskit ブログの投稿で述べたように、私たちは、翻訳された言語が、翻訳者、校正者、および翻訳リーダーで構成される翻訳チームからの十分なサポートを確保したいと考えています。 翻訳のリーダーになりたい場合、または新しい翻訳プロジェクトチームに参加したい場合は、 GitHub issue を開いてQiskitチームと会話を開始した上で、翻訳プロジェクトのメンバーを募集できます。

  7. 参加 ボタンをクリックし、Crowdinプロジェクトに参加する理由を尋ねるダイアログボックスに PRのURLを貼り付けます

Crowdinプロジェクトの管理者があなたの申請を確認し、できるだけ早くアクセス権を付与するようにします。

ソースからのビルド

以下の方法で Qiskit/qiskit のローカルクローンからドキュメントのローカルコピーをビルドすることが出来ます。

  1. Qiskitリポジトリをクローンします。

    git clone https://github.com/Qiskit/qiskit.git
    
  2. レポジトリをクローンすると、qiskit という名前のローカル・フォルダが作成されます。

    cd qiskit
    
  3. Qiskit/qiskit クローンの場所に移動し、端末ウィンドウから以下のコマンドを実行してドキュメントをビルドします。

    tox -edocs
    

    tox コマンドが無い場合には、以下を実行してインストールしてください:

    pip install tox
    

ローカル RST ファイルを変更した場合には、端末ウィンドウで /doc/ に移動し、以下のコマンドを実行すると HTML ファイルを更新することができます:

tox -edocs

これで スタイル化された HTML バージョンのローカルドキュメントリポジトリが /docs/_build/html/ にビルドされます。

ソースからインストールする方法

ソースからエレメントをインストールすることにより、Python Package Index (PyPI) リポジトリのバージョンを使う代わりに、最新のQiskitバージョンにアクセスすることが出来ます。これにより、Qiskit コードの最新版を調査したり、拡張することがより効果的にできるようになります。

ソースからエレメントやコンポーネントをインストールする時には、デフォルトでは、安定 バージョン( pip パッケージとして公開されているコードベースと同じもの) ではなく、 開発 バージョン( master git ブランチに該当) が使われます。 エレメントやコンポーネントの 開発 バージョンは通常新しい機能や変更が含まれているため、一般的には他の項目についても 開発 バージョンを利用することが求められています。

注釈

Terraと Aerのパッケージはソースからビルドするためにコンパイラーが必要なため、インストール前に準備します。Ignis、Aqua、IBM Quantum Provider バックエンドにはコンパイラーは必要ありません。

pip のバージョンがソースバージョンより古い場合に、要求するものよりも古いバージョンをインストールしてしまうことを防ぐため、ソースからエレメントをインストールするには以下の順番で実施します:

  1. qiskit-terra

  2. qiskit-aer

  3. qiskit-ignis

  4. qiskit-aqua

  5. qiskit-ibmq-provider (IBM Quantum デバイスやオンライン・シミュレーターに接続する場合)

いくつかのコンポーネントとエレメントで同時に作業したい場合には、各エレメントに対して以下のステップを踏みます。

注釈

Pythonの名前空間パッケージを使用しているため、パッケージのインストール方法には注意する必要がります。もしソースからエレメントをインストールすることを考えている場合は、qiskit メタパッケージを使用しないでください。また、このガイドに従って、開発用に別の仮想環境を使用してください。もし、既存のインストールと開発環境を混在させる場合は、https://github.com/pypa/sample-namespace-packages/blob/master/table.md を参照して、連携するインストール方法の組み合わせを確認してください。

仮装開発環境のセットアップ

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

ソースから Terra をインストールする

ソースからインストールするには、お使いのシステム上にC++11をサポートするC++コンパイラが必要です。

ほとんどのLinuxプラットフォームには、必要なGCCコンパイラがインストール済みです。

macOSを使用している場合は、XCodeをインストールすることで、Clangのコンパイラをインストールすることができます。ターミナル・ウィンドウを開き以下のコマンドを入力して、XCodeとClangがイントールされていることを確認します。

clang --version

以下のコマンドでXCodeとClandをインストールします。

xcode-select --install

Windowsでは、Visual C++ Compilerを Webの Build Tools for Visual Studio 2017 からインストールする方法が最も簡単です。その他に Visual Studio 2015 あるいは 2017をインストールする方法もありますが、その際にはインストールオプションの C++ compiler を選択することを忘れない様にしてください。

コンパイラがインストールされたら、Qiskit Terraのイントール準備完了です。

  1. Terraレポジトリをクローンします。

    git clone https://github.com/Qiskit/qiskit-terra.git
    
  2. レポジトリをクローンすると、``qiskit-terra``という名前のローカル・フォルダが作成されます。

    cd qiskit-terra
    
  3. 作成された``qiskit-terra``ディレクトリから、Pythonの必要なライブラリをインストールします。

    pip install cython
    
  4. もし、テストを実行したり文法をチェックしたい場合は、開発者向けライブラリをインストールします。

    pip install -r requirements-dev.txt
    
  5. ``qiskit-terra``をインストールします。

    pip install .
    

編集可能モード(プロジェクトのコードを変更しても再インストールする必要なし) でインストールする場合は、次の手順を実行します:

pip install -e .

Terraのインストール後、サンプル・コードを実行することができます。サンプルを実行するには以下のコマンドを使用します:

python examples/python/using_qiskit_terra_level_0.py

注釈

他のコンポーネントをインストールしない場合、qiskit-terraはqiskit-aerとqiskit-ibmq-providerの両方がインストールされていないことを示す RuntimeWarning を発します。これは追加要素を使用するつもりだが、インストールされていないことに気づかなかったり、AerやIBM Quantum Providerのインストールが何らかの理由でインストールが失敗しているために警告を発します。これらの警告を抑制したい場合は、以下を追加してください:

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

コード内にて、qiskit をまず最初にインポートするように指定します。 これにより、欠落しているqiskit-aerおよびqiskit-ibmq-providerに関する警告が抑制されますが、qiskitまたは他のパッケージからのその他の警告は継続して表示されます。

Aerのソースコードからのインストール

  1. Aerレポジトリをクローンします。

    git clone https://github.com/Qiskit/qiskit-aer
    
  2. ビルドの必要要件をインストールします。

    pip install cmake scikit-build cython
    

この後、Aerをインストールする手順は、使用しているオペレーティング・システムによって異なります。AerはPythonインターフェースを持つコンパイルされたC++プログラムなので、AerバイナリをビルドするのにPythonへの依存性はありませんが、作成されたバイナリはオペレーティング・システムに依存するため普遍的にインストールすることはできません。

  1. コンパイラの必要要件をインストールします。

    AerをビルドするにはC++コンパイラと開発ヘッダーが必要です。

    Fedoraもしくは同等のLinux ディストリビューションを使っている場合は、次のコマンドでインストールできます:

    dnf install @development-tools
    

    Ubuntu/Debianを使っている場合は以下の通りです:

    apt-get install build-essential
    
  2. OpenBLASの開発ヘッダーをインストールします。

    Fedoraもしくは同等のLinux ディストリビューションを使っている場合は、次のコマンドでインストールできます:

    dnf install openblas-devel
    

    Ubuntu/Debianを使っている場合は以下の通りです:

    apt-get install libopenblas-dev
    
  1. 依存関係をインストールします。

    macOSで Clang コンパイラを使用するには、 OpenMP をサポートするための追加のライブラリをインストールする必要があります。 brew を使用して、この依存関係およびその他の依存関係をインストールできます。

    brew install libomp
    
  2. 次にBLAS実装をインストールします。OpenBLAS が一般的な選択です。

    brew install openblas
    

    次に、Xcode Command Line Tools をインストールします。

    xcode-select --install
    

Windowsでは、すべての依存関係をインストールするために Anaconda3 または Miniconda3 を使用する必要があります 。

  1. コンパイラの必要要件をインストールします。

    conda install --update-deps vs2017_win-64 vs2017_win-32 msvc_runtime
    
  2. バイナリをインストールし、依存関係をビルドします。

    conda install --update-deps -c conda-forge -y openblas cmake
    
  1. qiskit-aerを直接ビルドしインストールします。

    pip 19.0.0 より前がインストールされていて、カスタム・ビルドが不要な環境の場合は、次を実行します:

    cd qiskit-aer
    pip install .
    

    このコマンドは、バイナリのビルドとAerのインストール両方を実行します。

    別な手法として、より新しいpipがインストールされている場合、もしくはカスタム要件がある環境の場合、手動でPython wheelをビルドすることができます。

    cd qiskit-aer
    python ./setup.py bdist_wheel
    

    wheelのビルドにカスタム・オプションを指定する必要がある場合は、:ref:`aer_wheel_build_options`を参照してください。

    Python wheelは、ビルド後Aerレポジトリの dist/ ディレクトリに保存されます。正確なバージョンは場合に依ります。

    cd dist
    pip install qiskit_aer-*.whl
    

    作成されたwheelの正確なファイル名は、開発中であるAerの現在のバージョンに依存します。

wheelビルドのカスタム・オプション

Aerビルドシステムは、 scikit-build <https://scikit-build.readthedocs.io/en/latest/index.html> __ を使用して、Pythonインターフェイスでビルドするときにコンパイルを実行します。 これは、 setuptools <https://setuptools.readthedocs.io/en/latest/> __ のインターフェースとして機能し、 CMake <https://cmake.org/> __ を呼び出して、ローカルシステムのバイナリをコンパイルします。

バイナリのコンパイルは複雑なため、ビルド・プロセスの特定の部分にオプションを渡す必要があるかもしれません。 変数を渡す方法は次のとおりです:

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

ここで、角括弧`[]`内の要素はオプションで、skbuild_optscmake_optsbuild_tool_opts はあなたの選択したフラグに置き換えます。CMake のオプションはこちら(https://cmake.org/cmake/help/v3.6/manual/cmake.1.html#options) にあります。例えば、以下のようなコマンドを実行できます:

python setup.py bdist_wheel -- -- -j8

これは基礎となるビルド・システム(この場合 Automake ) に -j8 フラグを渡して、8プロセッサを使って並列にビルドしたいことを伝えています。

例えば、Linuxでのこれらのフラグの一般的な使用例は、使用するC++コンパイラのバージョン(通常デフォルトが古すぎる) を特定のものに指定することがあげられます:

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

ここでは、Aerをコンパイルするとき、デフォルトのg++ではなくg++-7コマンドを使うようCMakeに伝えています。

他の一般的な使用例は、環境によって、プラットフォーム名を指定したり、静的リンクを無効にしたりする必要がある場合が考えられます。

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

ここで、--plat-name はsetuptoolsのフラグでパッケージのメタデータ内で使用されるプラットフォーム名を指定します。-DSTATIC_LINKING はCMakeのフラグで静的リンクを無効にするために使用されます。-j8 はAutomakeのフラグで、コンパイラに8プロセッサを使用するよう伝えます。

プラットフォームに依存する共通オプションのリストは以下の通りです。

プラットフォーム

ツール

オプション

ユースケース

全て

Automake

-j

後ろに数字が続くこのオプションは、コンパイラが使用するプロセッサの数を指定します。

Linux

CMake

-DCMAKE_CXX_COMPILER

特定のC++コンパイラを指定するときに使用します。デフォルトのg++が古すぎる場合は、しばしば必要になります。

OSX

setuptools

–plat-name

出力Pythonパッケージ内のプラットフォーム名を指定する時に使用します。

OSX

CMake

-DSTATIC_LINKING

静的リンクを使用するか否かを指定する時に使用します。

注釈

これらのオプションの中にはプラットフォーム固有ではないものがあります。これらの特定のプラットフォームは、環境で一般的に使用されるためリストされています。 詳しくはツールの資料を参照してください。

Ignisのソースコードからのインストール

  1. Ignisレポジトリをクローンします。

    git clone https://github.com/Qiskit/qiskit-ignis.git
    
  2. レポジトリをクローンすると、qiskit-ignis という名前のローカル・フォルダが作成されます。

    cd qiskit-ignis
    
  3. テストや文法チェックを実行したい場合は、開発者要件をインストールします。ソースコードからインストール場合、qiskit-ignisパッケージをインストールおよび使用するために、これは必須ではありません。

    pip install -r requirements-dev.txt
    
  4. Ignisをインストールします。

    pip install .
    

編集可能モード(プロジェクトのコードを変更しても再インストールする必要なし) でインストールする場合:

pip install -e .

Aquaのソースコードからのインストール

  1. Aquaレポジトリをクローンします。

    git clone https://github.com/Qiskit/qiskit-aqua.git
    
  2. レポジトリをクローンすると、qiskit-aqua という名前のローカル・フォルダが作成されます。

    cd qiskit-aqua
    
  3. テストや文法チェックを実行したい場合は、開発者要件をインストールします。ソースコードからインストール場合、qiskit-aquaパッケージをインストールおよび使用するために、これは必須ではありません。

    pip install -r requirements-dev.txt
    
  4. Aquaをインストールします。

    pip install .
    

編集可能モード(プロジェクトのコードを変更しても再インストールする必要なし) でインストールする場合:

pip install -e .

IBM Qプロバイダーのソースコードからのインストール

  1. qiskit-ibmq-providerレポジトリをクローンします。

    git clone https://github.com/Qiskit/qiskit-ibmq-provider.git
    
  2. レポジトリをクローンすると、qiskit-ibmq-provider という名前のローカル・フォルダが作成されます。

    cd qiskit-ibmq-provider
    
  3. テストや文法チェックを実行したい場合は、開発者要件をインストールします。ソースコードからインストール場合、qiskit-ibmq-providerパッケージをインストールおよび使用するために必須ではありません。

    pip install -r requirements-dev.txt
    
  4. qiskit-ibmq-providerをインストールします。

    pip install .
    

編集可能モード(プロジェクトのコードを変更しても再インストールする必要なし) でインストールする場合:

pip install -e .