Merge pull request qulacs#444 from qulacs/443-state-tutorial-0.5.3

add make_superposition(), make_mixture() to tutorial

doc/en/source/guide/2.0_python_advanced.ipynb

@@ -783,6 +783,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
@@ -792,8 +793,10 @@
     "\n",
     "**It is fundamentally different in behavior from the operation of the same name in `QuantumState`, which corresponds to the quantum state**\n",
     "\n",
-    "-- `add_state` of `QuantumState` creates superpositon, but `add_state` of `DensityMatrix` create mixed state\n",
-    "-- The operation corresponding to `multiply_coef(z)` of `QuantumState` is `multiply_coef(abs(z)**2)` for `DensityMatrix`"
+    "- `add_state` of `QuantumState` creates superpositon, but `add_state` of `DensityMatrix` create mixed state\n",
+    "- The operation corresponding to `multiply_coef(z)` of `QuantumState` is `multiply_coef(abs(z)**2)` for `DensityMatrix`\n",
+    "\n",
+    "Using `state.make_superposition()` `state.make_mixture()` is recommended since `add_state()` `multiply_coef()` make users confused with those generated by `QuantumState`."
    ]
   },
   {
@@ -885,6 +888,46 @@
     "print(obtained)"
    ]
   },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Creating superposition states and mixture states\n",
+    "\n",
+    "You can create superposition states and mixture states by using `make_superposition()` `make_mixture()` in `state` module.\n",
+    "These states can also be created by applying `add_state()` `multiply_coef()` to `QuantumState` `DensityMatrix`, but is deprecated due to low readability."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from qulacs import QuantumState, DensityMatrix\n",
+    "from qulacs.state import make_superposition, make_mixture\n",
+    "# from QuantumState |a> and |b>, create a superposition state p|a> + q|b>\n",
+    "a = QuantumState(2)\n",
+    "a.set_computational_basis(0b00)\n",
+    "b = QuantumState(2)\n",
+    "b.set_computational_basis(0b11)\n",
+    "p = 1 / 2\n",
+    "q = 1 / 2\n",
+    "c = make_superposition(p, a, q, b)\n",
+    "print(c.get_vector())\n",
+    "# from QuantumState |a> and DensityMatrix |b><b|, create a mixture state p|a><a| + q|b><b|\n",
+    "# You can also create a mixture states from two QuantumState or two DensitMatrix\n",
+    "a = QuantumState(2)\n",
+    "a.set_computational_basis(0b00)\n",
+    "b = DensityMatrix(2)\n",
+    "b.set_computational_basis(0b11)\n",
+    "p = 1 / 2\n",
+    "q = 1 / 2\n",
+    "c = make_mixture(p, a, q, b)\n",
+    "print(c.get_matrix())"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

doc/ja/source/guide/2.0_python_advanced.md

@@ -595,6 +595,8 @@ device cpu
 - `QuantumState` の `add_state` は量子重ね合わせ状態を作りますが、`DensityMatrix` の `add_state` は混合状態を作ります。
 - `QuantumState` での `multiply_coef(z)` に対応する操作は `DensityMatrix` では `multiply_coef(abs(z)**2)` になります。
 
+これらの関数は `QuantumState` で生成されたものと混ざって混乱しやすいため、`state.make_superposition()` `state.make_mixture()` の使用を推奨します。
+
 ```python
 from qulacs import DensityMatrix
 state = DensityMatrix(2)
@@ -671,6 +673,45 @@ print(obtained)
 20
 ```
 
+### 重ね合わせ状態・混合状態の作成
+
+重ね合わせ状態や混合状態は  `state` モジュールの `make_superposition()` `make_mixture()` を使うことで作成できます。
+これらの状態は `QuantumState` `DensityMatrix` に `add_state()` や `multiply_coef()` を適用することで作成することもできますが、可読性が低いため非推奨です。
+
+```python
+from qulacs import QuantumState, DensityMatrix
+from qulacs.state import make_superposition, make_mixture
+
+# QuantumState |a> と |b> について、重ね合わせ状態 p|a> + q|b> を生成する
+a = QuantumState(2)
+a.set_computational_basis(0b00)
+b = QuantumState(2)
+b.set_computational_basis(0b11)
+p = 1 / 2
+q = 1 / 2
+c = make_superposition(p, a, q, b)
+print(c.get_vector())
+
+# QuantumState |a> と DensityMatrix |b><b| について、混合状態 p|a><a| + q|b><b| を生成する
+# QuantumState 同士や DensityMatrix 同士でも混合状態を生成することができる
+a = QuantumState(2)
+a.set_computational_basis(0b00)
+b = DensityMatrix(2)
+b.set_computational_basis(0b11)
+p = 1 / 2
+q = 1 / 2
+c = make_mixture(p, a, q, b)
+print(c.get_matrix())
+```
+
+```
+[0.5+0.j 0. +0.j 0. +0.j 0.5+0.j]
+[[0.5+0.j 0. +0.j 0. +0.j 0. +0.j]
+ [0. +0.j 0. +0.j 0. +0.j 0. +0.j]
+ [0. +0.j 0. +0.j 0. +0.j 0. +0.j]
+ [0. +0.j 0. +0.j 0. +0.j 0.5+0.j]]
+```
+
 ## 量子ゲート
 
 ### 量子ゲートに共通の操作