diff --git a/.gitignore b/.gitignore index 2ea6b208f6d9..a230ffb29f7e 100644 --- a/.gitignore +++ b/.gitignore @@ -118,7 +118,7 @@ test/python/test_qasm_python_simulator.pdf doc/_build/* -doc/_autodoc/* +doc/**/_autodoc qiskit/bin/* diff --git a/Makefile b/Makefile index 0a59f4d00261..9341dca6bd2b 100644 --- a/Makefile +++ b/Makefile @@ -40,9 +40,12 @@ profile: doc: export PYTHONPATH=$(PWD); \ - better-apidoc -f -o doc/_autodoc -d 5 -e -t doc/_templates/better-apidoc qiskit qiskit/tools "qiskit/extensions/standard/[a-z]*"; \ - sphinx-autogen -t doc/_templates doc/_autodoc/*; \ - make -C doc html + for LANGUAGE in "." "ja"; do \ + better-apidoc -f -o doc/$$LANGUAGE/_autodoc -d 5 -e -t doc/_templates/better-apidoc qiskit qiskit/tools "qiskit/extensions/standard/[a-z]*"; \ + sphinx-autogen -t doc/_templates doc/$$LANGUAGE/_autodoc/*; \ + make -C doc -e BUILDDIR="_build/$$LANGUAGE" -e SOURCEDIR="./$$LANGUAGE" html; \ + done clean: make -C doc clean + make -C doc -e BUILDDIR="_build/ja" -e SOURCEDIR="./ja" clean diff --git a/doc/Makefile b/doc/Makefile index e4bde1dccd10..ad3ea50691c9 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -12,7 +12,11 @@ BUILDDIR = _build help: @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -.PHONY: help Makefile +.PHONY: help Makefile clean + +clean: + rm -rf "$(BUILDDIR)" + rm -rf "$(SOURCEDIR)/_autodoc" # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). diff --git a/doc/conf.py b/doc/conf.py index a91f8aacfd20..9f8d425fc323 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -99,7 +99,7 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. # This patterns also effect to html_static_path and html_extra_path -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '_autodoc/modules.rst'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '_autodoc/modules.rst', 'ja'] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' diff --git a/doc/ja/conf.py b/doc/ja/conf.py new file mode 100644 index 000000000000..cf2ca368ed2c --- /dev/null +++ b/doc/ja/conf.py @@ -0,0 +1,19 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +""" +Language specific configuration file, inheriting from the main /doc +conf.py file and adjusting the variables that depend on the language. +""" + +import os +import sys + +sys.path.insert(0, os.path.abspath('..')) +from conf import * + +language = 'ja' +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', '_autodoc/modules.rst'] + +html_theme_path = ['../'] +html_logo = '../theme/static/qiskit-logo-white-no-margin.gif' +html_favicon = '../theme/static/favicon.ico' diff --git a/doc/ja/dev_introduction.rst b/doc/ja/dev_introduction.rst new file mode 100644 index 000000000000..b1561d2b966c --- /dev/null +++ b/doc/ja/dev_introduction.rst @@ -0,0 +1,64 @@ +ライブラリの構成 +============= + +プログラミング インターフェース +-------------------------- + +*qiskit* ディレクトリがメインのPythonモジュールで +:py:class:`QuantumProgram `、 +:py:class:`QuantumRegister `、 +:py:class:`ClassicalRegister `、 +:py:class:`QuantumCircuit `のインターフェースを含みます。 + +実行手順は次の通りです。ユーザーは *QuantumProgram* （量子プログラム）を作成しそれに +複数の量子回路の生成、変更、コンパイル、と実行ができます。 +各 *QuantumCircuit* （量子回路）には *QuantumRegister* （量子レジスター）か +*ClassicalRegister* （古典レジスター）があります。 +これらのオブジェクトのメソッドを通じて、量子ゲートを適用して量子回路を定義します。 +*QuantumCircuit* は **OpenQASM** コードを出力することができます。 +このコードは *qiskit* ディレクトリの他のコンポーネントに流すことができます。 + +:py:mod:`extensions ` ディレクトリは他の量子ゲートやアルゴリズムのサポートに必要な +量子回路の拡張のモジュールを含みます。 +現在は典型的な量子ゲートを定義した :py:mod:`standard ` 拡張が存在します。 + +内部モジュール +------------ + +以下のディレクトリは開発中の内部モジュールを含みます: + +- :py:mod:`qasm ` モジュールは **OpenQASM** ファイルを解析します。 +- :py:mod:`unroll ` モジュールはターゲットのゲートに応じて **OpenQASM** の翻訳と“unroll(展開)”を行います。 + (ゲート文のサブルーチンやループの展開も必要に応じて行います) +- :py:mod:`dagcircuit ` モジュールは量子回路をグラフとして処理します。 +- :py:mod:`mapper ` モジュールは、量子回路をカップリング（直接操作可能な量子ビットのペア）の制限がないバックエンドから制限のある実機で実行するために量子回路の変換を行います。 +- :py:mod:`backends ` モジュールは量子回路のシミュレーターを含みます。 +- *tools* ディレクトリはアプリケーション、分析、可視化のメソッドを含みます。 + +量子回路は以下の様にコンポーネントの間を流れます。 +プログラミングインターフェースを用いて生成した **OpenQASM** 量子回路はテキストか *QuantumCircuit* オブジェクトです。 +**OpenQASM** ソースコードはファイルか文字列で、 *Qasm* オブジェクトに渡されます。 +そして、ソースコードはparseメソッドで分析されて抽象構文木(abstract syntax tree, **AST**)が生成されます。 +**AST** は *Unroller* に渡されます。*Unroller* は異なる *UnrollerBackend* のいずれかを取り付けることができます。 +テキストを出力する *PrinterBackend*、シミュレーターと実機のバックエンドの入力を生成する *JsonBackend*、 +*DAGCircuit* を生成する *DAGBackend*、 *QuantumCircuit* オブジェクトを生成する *CircuitBackend* があります。 +*DAGCircuit*　は「展開された」**OpenQASM** の回路を有向非巡回グラフ(directed acyclic graph, DAG)として持ちます。 +*DAGCircuit* は回路構成の表現、変換、性質の計算、結果を **OpenQASM** で出力するメソッドがあります。 +この全体の流れは*mapper* モジュールが量子回路を、*CouplingGraph* で定義されたカップリング（直接操作可能な量子ビットのペア）の実機で実行するために変換するために行われます。 +このコンポーネントの構成は将来的に変更の可能性があります。 + +量子回路が現在のモジュールでどのように変換されるかを以下の図にまとめます。 + + + +.. image:: ../images/circuit_representations.png + :width: 600px + :align: center + +いくつかの unroller バックエンドとその出力は以下にまとめます: + + + +.. image:: ../images/unroller_backends.png + :width: 600px + :align: center diff --git a/doc/ja/example_real_backend.rst b/doc/ja/example_real_backend.rst new file mode 100644 index 000000000000..2f698ddbdcb4 --- /dev/null +++ b/doc/ja/example_real_backend.rst @@ -0,0 +1,40 @@ +実機バックエンドの例 +^^^^^^^^^^^^^^^^^ + +.. code-block:: python + :linenos: + + from qiskit import QuantumProgram + + # 初めてのQuantumProgramオブジェクトのインスタンス生成 + Q_program = QuantumProgram() + + # APIトークンの設定 + # トークンは次のURLから入手可能です。 https://quantumexperience.ng.bluemix.net/qx/account, + # "Personal Access Token"のセクションを参照してください。 + QX_TOKEN = "API_TOKEN" + QX_URL = "https://quantumexperience.ng.bluemix.net/api" + + # APIをセットアップしてプログラムの実行。 + # APIトークンとQXのURLが必要です。 + Q_program.set_api(QX_TOKEN, QX_URL) + + # 2量子ビットの量子レジスターを生成して"qr"と名づけます。 + qr = Q_program.create_quantum_register("qr", 2) + # 2ビットの古典レジスターを生成して"cr"と名づけます。 + cr = Q_program.create_classical_register("cr", 2) + # 量子レジスター"qr"と古典レジスター"cr"を使った量子回路"qc"を生成ます。 + qc = Q_program.create_circuit("superposition", [qr], [cr]) + + # Hゲートを量子ビット0に適用して量子重ね合わせを作ります。 + qc.h(qr[0]) + + # "qr"の量子状態を観測し、その結果を"cr"に格納します。 + qc.measure(qr, cr) + + # 量子回路をコンパイルして実機のバックエンドibmqx2で実行します。 + result = Q_program.execute(["superposition"], backend='ibmqx2', shots=1024) + + # 結果を表示します。 + print(result) + print(result.get_data("superposition")) diff --git a/doc/ja/index.rst b/doc/ja/index.rst new file mode 100644 index 000000000000..635d4d45cf0a --- /dev/null +++ b/doc/ja/index.rst @@ -0,0 +1,54 @@ +.. QISKit documentation master file, created by + sphinx-quickstart on Tue Jul 25 18:13:28 2017. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +======================== +QISKit マニュアル +======================== + +Quantum Information Software Kit (QISKit, 量子情報ソフトウェアキット)は +`OpenQASM `_　とIBM Q Experience(QX) +を利用してプログラミングをするためのPythonソフトウェア開発キット(SDK)です。 + + +目次 +===== + +.. toctree:: + :maxdepth: 2 + + インストール + 入門 + QISKit概要 + 開発マニュアル + SDKリファレンス <_autodoc/qiskit> + +Python モジュール +=============== + +主要モジュール +------------ + +.. autosummary:: + :nosignatures: + + qiskit.QuantumProgram + qiskit.QuantumCircuit + +:ref:`modindex` + +開発者 (アルファベット順) +====================== + +Jim Challenger, Andrew Cross, Ismael Faro, Jay Gambetta, Juan Gomez, +Paco Martin, Antonio Mezzacapo, Jesus Perez, and John Smolin, Erick Winston, +Chris Wood. + +将来のリリースでこのプロジェクトにコードの貢献をした方の名前を追加します。 + +翻訳者（順不同） +============= + +今道 貴司 +ルディー・レイモンド diff --git a/doc/ja/install.rst b/doc/ja/install.rst new file mode 100644 index 000000000000..d1b042faac5e --- /dev/null +++ b/doc/ja/install.rst @@ -0,0 +1,144 @@ +====================== +インストールとセットアップ +====================== + +インストール +============ + +1. ツールの入手 +---------------- + +QISKitを利用するには少なくとも`Python 3.5か以降 `__ と +`Jupyter Notebooks `__ を +インストールしておく必要があります。 +(後者はチュートリアルで対話的に操作することをお勧めします)。 + +一般ユーザーにQISKitが依存する多くのライブラリが含まれている +`Anaconda 3 `__ という +Python ディストリビューションをお勧めします。 + +Mac OS Xのユーザーに、Xcodeが役に立ちます: https://developer.apple.com/xcode/ + +QISKitに貢献したいか拡張したいユーザーにはGitもインストールする必要があります: https://git-scm.com/download/. + + +2. PIP インストール +----------------- + +QISKitをインストールする最も簡単な方法はPIP tool(Pythonのパッケージマネージャー)を利用することです。 + +.. code:: sh + + pip install qiskit + +3. レポジトリのインストール +----------------------- + +それ以外にもローカルにQISKit SDKのレポジトリのクローンを作成してそのディレクトリで作業するのも一般的です: + +- もしGitをインストールしている場合は、以下のコマンドを実行してください: + +.. code:: sh + + git clone https://github.com/QISKit/qiskit-sdk-py + cd qiskit-sdk-py + +- もしGitをインストールしていない場合は、 +　　`QISKit SDK GitHub repo `__ の +　　"Clone or download"ボタンをクリックして、 +　その後ダウンロードしたファイルを展開し、そのディレクトリーに移動し作業を開始します。 + +3.1 環境の設定 +^^^^^^^^^^^^^^^^^^^^^^^^^ + +QISKitを単独で機能するライブラリとして使うには全ての依存するライブラリもインストールする必要があります。 + +.. code:: sh + + # システムに依存しますが, 必要に応じて "sudo -H" をコマンドの前に追加します。 + pip install -r requires.txt + +チュートリアルを利用するにはAnacondaの環境をセットアップして依存するライブラリをインストールします。: + +- LinuxかMac OS X (Xcodeインストール済み)の場合、以下のコマンドを実行します。 + +.. code:: sh + + make env + +- Mac OS X (Xcodeなし)の場合, 以下のコマンドを実行します: + +.. code:: sh + + conda create -y -n QISKitenv python=3 pip scipy + activate QISKitenv + pip install -r requires.txt + +- Windowsの場合、Anacondaのプロンプトで以下のコマンドを実行します: + +.. code:: sh + + .\make env + + +4. APIトークンの設定 +--------------------------- + +- `IBM Q Experience `__ + のアカウントがない場合は作成します。 +- IBM Q Experienceのウェブサイトの“My Account” > “Personal Access Token” + からAPIトークンを取得します。 +- Qconfig.pyというファイルにAPIトークンを書き込きます。 + まずデフォルトのQconfig.pyをコピーします。 +　　　(Windowsの場合 ``cp`` を ``copy`` で置き換えます): + +.. code:: sh + + cp Qconfig.py.default Qconfig.py + +- Qconfig.pyをエディターで開き、``#APItoken``で始まる行の``#``を取り除き、 + あなたのAPIトークンを記入して保存します。 + +Jupyterのチュートリアルのインストール +================================ + +QISKitプロジェクトはチュートリアルをJupyterノートブックの形式で提供します。 +ノートブックはPythonのコードが埋め込まれたウェブページのようなものです。 +埋め込まれたコードを実行するには``Shift+Enter``を押すか、 +ページ上部のツールバーを使います。 +出力は即座にページの下に表示されます。多くの場合埋め込まれたコードは上から順に実行します。 +チュートリアルを使いはじめるには以下の通りにします。 + + +1.1 インストール +---------------------- +- チュートリアルのダウンロード: https://github.com/QISKit/qiskit-tutorial/archive/master.zip +- zipファイルの展開 +- ターミナルで"qiskit-tutorial-master"のディレクトリーに移動し、以下を実行する: + +.. code:: sh + + jupyter notebook index.ipynb + +チュートリアルに関する詳しい説明は +`qiskit-tutorial repository `__ +を参照してください。 + +FAQ +=== + +もし依存ライブラリを更新してエラーが発生した場合以下のコマンドを試してみてください: + +- システムに依存しますが, 必要に応じて "sudo -H" をコマンドの前に追加してください。 + +.. code:: sh + + pip install -U --no-cache-dir IBMQuantumExperience + +- 修正: 以下のコマンドを実行します。 + +.. code:: sh + + curl https://bootstrap.pypa.io/ez_setup.py -o - | python + +プロジェクトのGitHubのWikiのQISKit troubleshootingのページにさらに情報があります。 diff --git a/doc/ja/qiskit.rst b/doc/ja/qiskit.rst new file mode 100644 index 000000000000..4369e95a5e10 --- /dev/null +++ b/doc/ja/qiskit.rst @@ -0,0 +1,34 @@ +QISKit 概要 +=========== + +設計思想 +---- + +QISKitは、深さが限定的な量子回路を設計して直近の応用を意識した量子コンピューターのアプリケーションを開発したり +実験を行うためのソフトウェア開発キットです。QISKitの中では量子プログラムは量子回路の配列として管理されています。 +プログラムのフローは、「ビルド」、「コンパイル」、「実行」の3つの段階で構成されています。 +「ビルド」ではユーザーが解きたい問題に対応する量子回路を作ります。 +「コンパイル」は量子回路をバックエンドで実行するための変換を行います。 +バックエンドは量子回路を実行する実体で、シミュレーターや実機の選択肢があります。 +実機のバックエンドも、量子ビット数やフィディレティーやQuantum Volume等が異なるものがあり、 +コンパイルはそのような制限のあるバックエンドに合わせて量子回路の変換を行います。 +「実行」はジョブを生成します。ジョブが終了すると結果のデータを得ることができます。 +量子プログラムの実行結果からは問題の解の他に、「量子化学」と「組合せ最適化」のチュートリアルに書いてあるう通りその結果を組合せることで次の量子プログラムを作成することもできます。 + + +プロジェクト概要 +-------------- +QISKitプロジェクトの構成は以下の通りです: + +* `QISKit SDK `_: + 量子コンピューターのプログラムやアプリケーションを開発して実験を行うためのPythonソフトウェア開発キット + +* `QISKit API `_: + IBM Q ExperienceのHTTP APIのPythonラッパー。 + IBM Q Experienceを通じて量子プログラムの実行が可能。 + +* `QISKit OpenQASM `_: + OpenQASMという中間言語の仕様書、例、マニュアルおよびツール群。 + +* `QISKit Tutorial `_: + Jupyterノートブックで書かれたQISKitのチュートリアル集。 diff --git a/doc/ja/quickstart.rst b/doc/ja/quickstart.rst new file mode 100644 index 000000000000..15e3c8a5b03a --- /dev/null +++ b/doc/ja/quickstart.rst @@ -0,0 +1,61 @@ +QISKit入門 +========== + +:py:class:`QuantumProgram ` オブジェクトがコードを書く際の起点になります。 +QuantumProgramは量子回路と量子レジスターと古典レジスターで構成されます。 +IBM Q Experienceを使ったことがある人にとって、量子回路はComposerの画面で設計するもののことです。 +QuantumProgramのメソッドは量子回路を実機やシミュレーターのバックエンドに転送し、実行の結果を得て、 +さらなる分析を行うことができます。 + +シミュレーター上で量子回路を設計して実行するには、以下のようにします。 + +.. code-block:: python + :linenos: + + from qiskit import QuantumProgram + qp = QuantumProgram() + + qr = qp.create_quantum_register('qr', 2) + cr = qp.create_classical_register('cr', 2) + qc = qp.create_circuit('Bell', [qr], [cr]) + + qc.h(qr[0]) + qc.cx(qr[0], qr[1]) + qc.measure(qr[0], cr[0]) + qc.measure(qr[1], cr[1]) + + result = qp.execute('Bell') + print(result.get_counts('Bell')) + +:code:`get_counts` メソッドは {計算基底:出現回数} の辞書オブジェクトを出力します。 +計算基底とは従来のビット列のことです。 + +.. code-block:: python + + {'00': 531, '11': 493} + +量子プロセッサー +-------- + +ユーザーはQASMで記述した量子回路をIBM Q Experience (QX)のクラウドプラットホームを通じて、 +実機の量子コンピューター（量子プロセッサー）で実行することができます。 +現在以下のチップが利用可能です: + +- ibmqx2: `5-qubit backend `_ + +- ibmqx3: `16-qubit backend `_ + +- ibmqx4: `5-qubit backend `_ + +- ibmqx5: `16-qubit backend `_ + +最新の実機の詳細については`IBM Q Experience バックエンド情報 `_ を参照してください。 + +.. include:: example_real_backend.rst + +プロジェクト構成 +-------------- + +Pythonのプログラム例は *examples* ディレクトリに、 +テストスクリプトは *test* ディレクトリにあります。 +*qiskit* ディレクトリがSDKのメインモジュールです。 diff --git a/tools/ghpages-documentation-deploy.sh b/tools/ghpages-documentation-deploy.sh index 99db298bfed4..b79d19bac282 100755 --- a/tools/ghpages-documentation-deploy.sh +++ b/tools/ghpages-documentation-deploy.sh @@ -28,7 +28,9 @@ TARGET_REPOSITORY_USER="QISKit" TARGET_REPOSITORY_NAME="qiskit.github.io" TARGET_DOC_DIR="documentation" SOURCE_DOC_DIR="doc/_build/html" +SOURCE_DOC_DIR_JA="doc/_build/ja/html" SOURCE_DIR=`pwd` +SOURCE_DIR_JA=`pwd`/ja # Build the documentation. make doc @@ -39,10 +41,12 @@ git clone https://github.com/$TARGET_REPOSITORY_USER/$TARGET_REPOSITORY_NAME.git cd $TARGET_REPOSITORY_NAME echo "Replacing $TARGET_DOC_DIR with the new contents ..." -git rm -r $TARGET_DOC_DIR +git rm -rf $TARGET_DOC_DIR +git rm -rf $TARGET_DOC_DIR_JA cp -r $SOURCE_DIR/$SOURCE_DOC_DIR $TARGET_DOC_DIR +cp -r $SOURCE_DIR/$SOURCE_DOC_DIR_JA $TARGET_DOC_DIR_JA git add $TARGET_DOC_DIR echo "Commiting and pushing changes ..." -git commit -m "Automated documentation update from SDK" -m "Commit: $TRAVIS_COMMIT" -m "Travis build: https://travis-ci.org/TRAVIS_REPO_SLUG/builds/$TRAVIS_BUILD_ID" -git push --force --quiet https://$GH_TOKEN@github.com/$TARGET_REPOSITORY_USER/$TARGET_REPOSITORY_NAME.git > /dev/null 2>&1 +git commit -m "Automated documentation update from SDK" -m "Commit: $TRAVIS_COMMIT" -m "Travis build: https://travis-ci.org/$TRAVIS_REPO_SLUG/builds/$TRAVIS_BUILD_ID" +git push --quiet https://$GH_TOKEN@github.com/$TARGET_REPOSITORY_USER/$TARGET_REPOSITORY_NAME.git > /dev/null 2>&1