Metadata-Version: 2.4
Name: qnumpy
Version: 0.1.0
Summary: NumPy designed around what qubits are good at: state-vector search, optimization, walks, factoring and Hamiltonian simulation, plus a cheap classical APQB tier.
Author: Qubit AI Project
License-Expression: MIT
Project-URL: Homepage, https://github.com/tapiocaTakeshi/qnumpy
Project-URL: Repository, https://github.com/tapiocaTakeshi/qnumpy
Project-URL: Issues, https://github.com/tapiocaTakeshi/qnumpy/issues
Project-URL: Changelog, https://github.com/tapiocaTakeshi/qnumpy/blob/main/CHANGELOG.md
Keywords: quantum-computing,quantum-simulator,state-vector,grover,shor,qaoa,quantum-walk,hamiltonian-simulation,numpy,apqb,qbnn,quantum-inspired
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.22
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# QNumPy

**量子ビットの「特技」から逆算して設計した NumPy。**

QNumPy は NumPy のドロップイン置き換え（`import qnumpy as qnp` で `qnp.linspace`、
`qnp.dot`、`qnp.linalg.svd` はそのまま動く）に、**二つの層**を足したものです。

| 層 | 持っているもの | コスト | 何に使うか |
|---|---|---|---|
| **状態ベクトル層** `qnumpy.quantum` | 重ね合わせ・**量子もつれ**・**干渉**・測定 | n量子ビットで 2ⁿ 振幅 | 探索、最適化、量子ウォーク、素因数分解、量子シミュレーション |
| **APQB 層** `qnumpy.apqb` / `QArray` | 重ね合わせ（実振幅のみ）・相関・制御可能な乱雑さ | O(n) | 相関エンコード、構造化ノイズ、乗算的相互作用（QBNN） |

APQB 層は位相を持たない実振幅の積状態なので、**もつれも干渉もありません**。
そこが量子計算の効き所なので、QNumPy の本体は状態ベクトル層です。

```python
import qnumpy as qnp

qnp.search([777], n_qubits=10)    # Grover：25 クエリ（古典は平均 512.5）
qnp.optimize(cost_matrix, p=3)    # QAOA：組合せ最適化
qnp.sample(state, shots=1000)     # 測定（Born 則）
qnp.quantum_walk(401, steps=60, kind="coined")   # 弾道的な広がり
qnp.factor(35)                    # Shor：位相推定による位数発見
qnp.simulate(hamiltonian, time=3.0)              # ハミルトニアン時間発展
```

## 量子ビットの 4 つの特技と、対応する API

| 特技 | QNumPy での表現 | 例 |
|---|---|---|
| **重ね合わせ** | `QuantumState` が 2ⁿ 個の複素振幅を保持 | `qnp.QuantumState.uniform(10)` は 1024 状態を同時に持つ |
| **量子もつれ** | 積状態に分解できない結合状態 | `bell.entanglement_entropy([0]) == 1.0`、`bell.concurrence() == 1.0` |
| **干渉** | 振幅が符号つきで足し合わされ、不要な状態が消える | `H → Z → H` が `X` になる。Grover の反転操作も、Shor の QFT も本質はこれ |
| **測定** | `|振幅|²` で 1 つのビット列に確定する | `qnp.sample(state, shots=1000)` → `Counts` |

## どこで効いて、どこで効かないか（重要）

* 普通の `a + b` や一般の配列処理は **CPU/GPU の仕事**です。QNumPy はそれらを
  そのまま NumPy に転送します（`qnp.add`, `qnp.einsum`, `qnp.linalg.*` …）。
* 状態ベクトル層は**古典計算機上のシミュレータ**です。n 量子ビットで 2ⁿ 振幅を
  扱うので、**実行時間は古典コードより速くなりません**。
* 代わりに各結果オブジェクトは、実機で意味を持つ**資源**を報告します。
  Grover なら `oracle_queries` と `classical_expected_queries`、Shor なら
  `n_qubits` と回路構造、シミュレーションなら Trotter ステップ数と誤差です。

```
qubits        amplitudes     memory
    10             1,024     16 KiB
    20         1,048,576     16 MiB
    30     1,073,741,824     16 GiB
    40 1,099,511,627,776     16 TiB
```

つまり QNumPy は「何でも速くなるライブラリ」ではなく、**量子ビットの特技が効く
問題の構造を、実際に動かして確かめるためのライブラリ**です。

## インストール

```bash
pip install qnumpy
```

依存は `numpy>=1.22` のみ、Python 3.9 以上で動きます。

開発用（リポジトリを clone した場合）:

```bash
pip install -e ".[dev]"   # + pytest / build / twine
python -m pytest
```

リリース手順は [RELEASING.md](RELEASING.md)、変更履歴は
[CHANGELOG.md](CHANGELOG.md) を参照してください。

## 実行できる例

```bash
python examples/qubit_basics.py            # 4つの特技と、そのコスト
python examples/grover_search.py           # 探索：クエリ数の比較、過回転
python examples/shor_factoring.py          # 素因数分解：位数発見のピーク
python examples/qaoa_maxcut.py             # 最適化：深さ p と到達エネルギー
python examples/quantum_walk_demo.py       # 量子ウォーク：弾道 vs 拡散
python examples/hamiltonian_simulation.py  # 時間発展：Trotter 誤差の収束
python examples/quickstart.py              # APQB 層の基礎
python examples/xor_parity.py              # QBNN：パラメータ数を揃えた比較
python examples/structured_noise.py        # APQB：構造化ノイズと η 制御
python examples/interaction_analysis.py    # QBNN：学習後の相互作用の可視化
```

---

## 1. 状態ベクトル：`QuantumState` と `QuantumCircuit`

```python
bell = qnp.QuantumState(2).h(0).cx(0, 1)
bell.probabilities()            # [0.5, 0, 0, 0.5]
bell.entanglement_entropy([0])  # 1.0 ビット（最大もつれ）
bell.concurrence()              # 1.0
bell.expectation("ZZ")          # +1.0（ペアは確定）
bell.expectation("ZI")          #  0.0（片方だけでは不確定）
qnp.sample(bell, shots=1000)    # Counts({'00': 473, '11': 527}, shots=1000)
```

ビット順序は **ビッグエンディアン**（量子ビット 0 が最上位ビット）です。
`QuantumState.basis(3, "101")` は量子ビット 0 と 2 が 1 の状態になります。

回路として書くこともできます。

```python
qc = qnp.QuantumCircuit(3).h(0).cx(0, 1).ccx(0, 1, 2)
qc.depth, qc.num_gates, qc.gate_counts()
print(qc.draw())
#  q0: -H-*-*-
#  q1: ---X-*-
#  q2: -----X-
state = qc.run()
qc.inverse().run(state)        # 元に戻る
```

主なメソッド：`h/x/y/z/s/t/p/rx/ry/rz/u`、`cx/cy/cz/cp/swap/ccx/mcz`、
`apply(gate, qubits)`、`apply_diagonal`、`apply_permutation`、
`measure`（射影あり）、`sample`、`expectation`、`reduced_density_matrix`、
`entanglement_entropy`、`concurrence`、`bloch_vectors`、`fidelity`、
`from_apqb` / `apqb_coordinates`（APQB 層との橋渡し）。

## 2. `qnp.search()` — Grover 探索

```python
res = qnp.search([777], n_qubits=10, shots=1000)
res.index                        # 777
res.probability                  # 0.9995
res.oracle_queries               # 25   ≈ (π/4)√1024
res.classical_expected_queries   # 512.5
res.query_speedup                # 20.5
```

オラクルは **述語関数・解のリスト・ブール配列**のいずれでも渡せます。

```python
qnp.search(lambda i: i * i % 91 == 4, n_qubits=7)
```

反復回数は既定で最適値 `⌊π/(4θ) − 1/2⌋`。回しすぎると振幅が**過回転**して
確率が落ちます（干渉は両刃であることの実演が `examples/grover_search.py` にあります）。
一般の初期状態に対しては `amplitude_amplification()` を使います。

## 3. `qnp.optimize()` — QAOA

```python
costs = qnp.quantum.maxcut_cost(adjacency)   # or a QUBO matrix, or a callable
res = qnp.optimize(costs, p=3)
res.bitstring, res.value, res.optimum, res.is_optimal, res.expectation
```

コストは `callable(bits) -> float`、QUBO 行列、長さ 2ⁿ のコストベクトルのいずれか。
`qubo_cost` / `ising_cost` / `maxcut_cost` のビルダを同梱しています。
外側のループは依存を増やさないよう Nelder–Mead を自前実装しています。

> 注意：対角コスト作用素の構築時点で全 2ⁿ ビット列を評価しているので、
> このシミュレータは既に厳密最適解を知っています（`res.optimum` がそれ）。
> QAOA の価値は「深さ p がどれだけ確率を集中させるか」を見ることにあります。

## 4. `qnp.sample()` — 測定

```python
qnp.sample(state, shots=1000)              # QuantumState
qnp.sample(circuit, shots=1000)            # QuantumCircuit（実行してから測定）
qnp.sample(qnp.qarray([0.6, -0.9]), 1000)  # APQB レジスタ（各ユニット独立）
qnp.sample(prob_vector, 1000)              # 長さ 2ⁿ の確率ベクトル
```

返り値の `Counts` は `dict` のサブクラスで、`.most_common()`、
`.probabilities()`、`.integers()` を持ちます。APQB レジスタの測定は、
その積状態 `QuantumState.from_apqb(r)` の測定と**同じ分布**になります
（テストで確認しています）。

## 5. `qnp.quantum_walk()` — 量子ウォーク

```python
walk = qnp.quantum_walk(401, steps=60, start=200, kind="coined")
walk.spread            # 32.5  （量子：t に比例＝弾道的）
walk.classical_spread  #  7.7  （古典：√t に比例＝拡散的）
walk.spread_ratio      #  4.2
```

連続時間ウォーク（隣接行列の `exp(-iAt)`）と離散コインウォークの両方に対応し、
**必ず同条件の古典ランダムウォークを併記**します。グラフは
`line_graph` / `cycle_graph` / `complete_graph`、または任意の隣接行列。

## 6. `qnp.factor()` — Shor の素因数分解

```python
res = qnp.factor(35, force_quantum=True)
res.factors    # (5, 7)
res.order      # a の位数（位相推定で取得）
res.n_qubits   # 18（= 2n カウント量子ビット + n 作業量子ビット）
res.method     # 'quantum'
```

偶数・完全冪・素数判定・gcd といった古典的な前処理（アルゴリズムの一部）を
先に行い、残りを量子位数発見で解きます。剰余乗算は基底状態の置換として適用します
（シミュレータの標準的なやり方で、生成される状態は同じです）。
`force_quantum=True` は gcd の偶然当たりを飛ばし、必ず量子経路を通します。

位数発見の中身は `order_finding(a, N)` で直接呼べます。
`a=7, N=15` では、カウントレジスタが `k = 0, 64, 128, 192`（= k·2⁸/4）に
きれいな 4 本のピークを作り、連分数展開から r = 4 が復元されます。

> シミュレーションは 2³ⁿ 振幅を要するので、試し割りより**遅い**です。
> 実証しているのはアルゴリズムの正しさと量子部分の所在であって、高速化ではありません。

## 7. `qnp.simulate()` — ハミルトニアンシミュレーション

```python
h = qnp.quantum.transverse_field_ising(4, coupling=1.0, field=0.6)
res = qnp.simulate(h, time=6.0, steps=120, observables=["ZIII", "IIIZ"])
res.observable("ZIII")     # 磁化の時間発展
h.ground_state()           # 厳密対角化による基底状態
```

* `method='trotter'`（既定、`order=1|2`）と `method='exact'`（厳密対角化）
* `compare_exact=True` で Trotter 忠実度を報告（dt を半分にすると 1 次は約 1/4、
  2 次は約 1/16 に誤差が減ることを確認できます）
* ハミルトニアンは `Hamiltonian([(係数, "ZZI"), ...])`、
  `transverse_field_ising`、`heisenberg`、または密なエルミート行列

各 Pauli 項は `exp(-iθP)|ψ⟩ = cosθ|ψ⟩ − i sinθ P|ψ⟩` で厳密に指数化しています。

## 8. `qnp.qft()` / `qnp.phase_estimation()`

```python
qnp.qft(state)                 # 周期的な振幅パターンを鋭いピークに変える
qnp.iqft(state)
qnp.phase_estimation(unitary, eigenstate, n_counting=8).phase
```

QFT は `n = 1..4` の全基底状態について DFT 行列と一致することをテストしています。

---

## 9. APQB 層（相関エンコードと QBNN）

APQB（調整可能擬似量子ビット）は、角度 θ ひとつで相関と乱雑さを同時に表す
古典的な計算単位です。位相を持たないため干渉ともつれはありませんが、
O(n) で済み、相関・構造化ノイズ・乗算的相互作用の道具として使えます。

```python
r = qnp.qarray([-1.0, 0.0, 0.5, 1.0])   # 相関座標 r = cos(2θ)
r.theta, r.eta, r.p0, r.z               # 角度 / 不確実性振幅 / Born確率 / 複素座標
r.r ** 2 + r.eta ** 2                   # == 1（単位円恒等式）
r * r                                   # 部分集合積 φ_S（積について閉じている）
```

| モジュール | 内容 |
|---|---|
| `qnumpy.apqb` | r↔θ↔η 変換、Born 確率、Bloch 幾何、密度行列、Bell/GHZ 限定の対応、制御信号 |
| `qnumpy.multilinear` | 部分集合積 φ_S、K 次相互作用基底（解析的 VJP つき）、Boolean 超立方体上の厳密 Fourier 展開 |
| `qnumpy.random` | Born 測定、Corr(X,Y)=r を満たす ±1 ペア、相関行列に沿った構造化ノイズ、η 駆動の dropout/temperature |
| `qnumpy.qbnn` | QBNN 層（乗算的ゲート、手導出の勾配）、Dense ベースライン、Adam/SGD |
| `qnumpy.linalg` | 相関行列ユーティリティ + `numpy.linalg` 転送 |

QBNN 層は通常のアフィン層に APQB 座標由来のゲートを加えたもので、
`lam=0` で通常のニューラルネットワークに**厳密に帰着**します。
勾配はすべて有限差分と一致することをテストで確認しています。
APQB 層の詳細は `examples/quickstart.py` と `examples/xor_parity.py` を参照してください。

二つの層は次で行き来します。

```python
state = qnp.QuantumState.from_apqb([0.5, -0.8])   # APQB → 積状態（必ず非もつれ）
state.apqb_coordinates()                          # 状態 → 各量子ビットの r = <Z>
```

これは**意図的に不可逆**です。Bell 状態の APQB 座標は全て 0 になりますが、
それは APQB が結合状態を表現できないことの表れです。

## テスト

```bash
python -m pytest -q      # 115 tests
```

主な検証内容：

- ゲートのユニタリ性と恒等式、任意の（逆順を含む）量子ビット指定でのゲート適用が
  クロネッカー積による明示的構成と一致すること
- Bell/GHZ のもつれエントロピーと concurrence、積状態の判定
- 干渉（H·Z·H = X、二重 H の打ち消し）
- QFT が DFT 行列と一致、位相推定が 2 進小数の位相を厳密に復元
- Grover の成功確率が `sin²((2k+1)θ)` と一致、最適反復回数、複数解の場合
- QAOA が小規模 MaxCut/QUBO の厳密最適解に到達、深さ p でエネルギーが単調改善
- 量子ウォークの σ ∝ t と古典の σ ∝ √t
- Shor が 15/21/35 を量子経路で分解、位数の検証、連分数
- Trotter 誤差が次数に応じて収束、厳密発展が級数展開の行列指数と一致、エネルギー保存
- APQB 側：単位円恒等式、Pearson 相関の導出、QBNN の全勾配の有限差分検証
- README/docstring の doctest

## 制限事項

- 状態ベクトルは 28 量子ビットで上限を設けています（2²⁸ 複素数 ≈ 4 GiB）。
  これは実装上の都合ではなく、古典シミュレーションの本質的な壁です。
- QAOA と `optimize` は全ビット列のコストを構築するため、n が大きい問題には
  使えません（構造を調べるための道具です）。
- Shor の剰余乗算は算術回路ではなく置換として実装しています。生成される状態は
  同じですが、実機で必要なゲート数の見積りには使えません。
- APQB 層は量子コンピュータのモデルではなく、`r = cos(2θ)` の導出は
  バランスした ±1 二値変数に対して厳密です。

## ライセンス

MIT
