quonic 0.2.0__py3-none-any.whl

quonic/__init__.py

@@ -0,0 +1,39 @@
+"""QuoNic —— 量子编程，像写 Python 一样简单。"""
+
+from . import gates
+from .compare import qeq, qgt, qlt
+from .compiler import RoutingError, decompose
+from .noise import NoiseModel, depolarizing
+from .qgate import qgate
+from .qif import cif, controlled, creg, cwhile, qif
+from .qint import QInt, mul
+from .qshow import qshow
+from .result import Result
+from .stack import reset
+from .topology import CouplingMap
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "qgate",
+    "qif",
+    "cif",
+    "controlled",
+    "creg",
+    "cwhile",
+    "qlt",
+    "qeq",
+    "qgt",
+    "mul",
+    "qshow",
+    "reset",
+    "gates",
+    "QInt",
+    "Result",
+    "NoiseModel",
+    "depolarizing",
+    "CouplingMap",
+    "RoutingError",
+    "decompose",
+    "__version__",
+]

quonic/algorithms/__init__.py

@@ -0,0 +1,27 @@
+"""算法模板：Grover 搜索 / VQE / QAOA / QPE。
+
+每个模板只依赖 numpy / scipy，不绑定具体后端；采样类算法
+（Grover、QPE）可切换 qiskit / cirq / pennylane 任意后端。
+"""
+
+from .grover import diffusion, grover, mark_state
+from .hamiltonians import from_qiskit_nature
+from .oracle import oracle
+from .qaoa import qaoa_maxcut
+from .qpe import qpe
+from .quantum_counting import quantum_counting
+from .shor import shor
+from .vqe import vqe
+
+__all__ = [
+    "grover",
+    "mark_state",
+    "diffusion",
+    "oracle",
+    "quantum_counting",
+    "shor",
+    "vqe",
+    "qaoa_maxcut",
+    "from_qiskit_nature",
+    "qpe",
+]

quonic/algorithms/grover.py

@@ -0,0 +1,109 @@
+"""Grover 搜索算法模板。
+
+搜索某个计算基态，最简单的方式是直接传比特串（mark_state 自动生成神谕）：
+
+    from quonic.algorithms import grover
+    result = grover("11", 2, shots=1024)   # 在 2 比特中搜索 |11>
+
+也可以提供自定义神谕（一个把目标态相位翻转的回调）：
+
+    from quonic.algorithms import grover, mark_state
+    result = grover(mark_state("11"), 2, shots=1024)
+"""
+
+import math
+
+from ..backends import get_backend
+from ..ir import Circuit, GateOperation
+
+
+def _add_diffusion(circuit, n):
+    for q in range(n):
+        circuit.add(GateOperation("h", (q,)))
+    for q in range(n):
+        circuit.add(GateOperation("x", (q,)))
+    _add_phase_flip_all_ones(circuit, n)
+    for q in range(n):
+        circuit.add(GateOperation("x", (q,)))
+    for q in range(n):
+        circuit.add(GateOperation("h", (q,)))
+
+
+def _add_phase_flip_all_ones(circuit, n):
+    # 对 |11...1> 施加 -1 相位（多控制 Z）
+    if n == 1:
+        circuit.add(GateOperation("z", (0,)))
+    else:
+        circuit.add(GateOperation("mcz", tuple(range(n))))
+
+
+def mark_state(bitstring):
+    """返回一个神谕回调，标记计算基态 |bitstring>。
+
+    比特串最右位是 qubit 0（与 qshow 的比特串约定一致）。
+    例：mark_state("11") 标记 |11>；mark_state("10") 标记 |10>（qubit0=0, qubit1=1）。
+    """
+    bitstring = str(bitstring)
+    if not bitstring or any(ch not in "01" for ch in bitstring):
+        raise ValueError(f"mark_state 需要只含 0/1 的比特串，收到 {bitstring!r}")
+    n = len(bitstring)
+
+    def oracle(circuit):
+        # 把目标态中的 0 位翻成 1，做全 1 相位翻转，再翻回来
+        for q in range(n):
+            if bitstring[n - 1 - q] == "0":
+                circuit.add(GateOperation("x", (q,)))
+        _add_phase_flip_all_ones(circuit, n)
+        for q in range(n):
+            if bitstring[n - 1 - q] == "0":
+                circuit.add(GateOperation("x", (q,)))
+
+    return oracle
+
+
+def grover(oracle, n_qubits, iterations=None, backend="auto", shots=1024):
+    """运行 Grover 搜索。
+
+    参数：
+        oracle: 神谕，可以是回调函数 oracle(circuit)，也可以直接传比特串
+            （如 "11"，等价于 mark_state("11")）。
+        n_qubits: 量子比特数。
+        iterations: 迭代次数，默认 floor(π/4 · √(2^n))。
+        backend: 采样后端（qiskit / cirq / pennylane）。
+        shots: 采样次数。
+
+    返回：Result（kind="counts"），result.counts 为采样直方图。
+    """
+    if isinstance(oracle, str):
+        if len(oracle) != n_qubits:
+            raise ValueError(
+                f"标记的比特串 '{oracle}' 长度 {len(oracle)} 与量子比特数 {n_qubits} 不一致"
+            )
+        oracle = mark_state(oracle)
+
+    circuit = Circuit()
+    for q in range(n_qubits):
+        circuit.add(GateOperation("h", (q,)))
+
+    if iterations is None:
+        iterations = int(math.pi / 4 * math.sqrt(2 ** n_qubits))
+
+    for _ in range(iterations):
+        oracle(circuit)
+        _add_diffusion(circuit, n_qubits)
+
+    return get_backend(backend).run(circuit, shots=shots)
+
+
+def diffusion(n_qubits):
+    """把 Grover 扩散算子（2|s><s| - I）追加到当前电路。
+
+    对 qubit 0..n_qubits-1 施加 H、X、多控制 Z、X、H 的序列，是振幅放大
+    （Grover 迭代）的核心一步，可与 qgate / mark_state 组合构建自定义搜索：
+        qgate(H, 0); qgate(H, 1); mark_state("11")(current_circuit()); diffusion(2)
+    """
+    from ..stack import current_circuit
+
+    circ = current_circuit()
+    _add_diffusion(circ, n_qubits)
+    return circ

quonic/algorithms/hamiltonians.py

@@ -0,0 +1,34 @@
+"""哈密顿量辅助：从外部量子化学库导入泡利哈密顿量。
+
+QuoNic 不内置化学数据库；分子的电子结构哈密顿量需要用户用
+Qiskit Nature / OpenFermion 等工具自行生成，再用本模块的适配器
+转成 vqe() 所需的 [(系数, 泡利串), ...] 格式。
+"""
+
+
+def from_qiskit_nature(op):
+    """把 Qiskit Nature（或 Qiskit）的 SparsePauliOp 转成 [(coeff, pauli), ...]。
+
+    op 需具备 .coeffs 和 .paulis 属性（qiskit.quantum_info.SparsePauliOp 满足）。
+
+    例（示意）：
+        from qiskit_nature.second_q.drivers import PySCFDriver
+        from qiskit_nature.second_q.mappers import JordanWignerMapper
+        # ... 用 PySCFDriver 得到 ElectronicStructureProblem，做 JW 映射 ...
+        qubit_op = problem.hamiltonian.second_q_op()  # 经 mapper 映射后是 SparsePauliOp
+        terms = from_qiskit_nature(qubit_op)
+        vqe(terms, n_qubits)
+
+    说明：
+        - 泡利串序已对齐 QuoNic 约定（左起第一个字符 = qubit 0），与 Qiskit 一致，无需反转。
+        - 分子哈密顿量在 JW 映射下系数为实数；若出现不可忽略的虚部会报错。
+    """
+    terms = []
+    for coeff, pauli in zip(op.coeffs, op.paulis):
+        if abs(coeff.imag) > 1e-8:
+            raise ValueError(
+                f"哈密顿量系数 {coeff} 含不可忽略的虚部，当前 VQE 仅支持实系数"
+            )
+        label = pauli.to_label() if hasattr(pauli, "to_label") else str(pauli)
+        terms.append((float(coeff.real), label))
+    return terms

quonic/algorithms/oracle.py

@@ -0,0 +1,42 @@
+"""@oracle 装饰器：把经典谓词编译成 Grover 相位神谕。
+
+     from quonic.algorithms import grover, oracle
+
+     @oracle(3)
+     def f(x):
+         return x == 5            # 标记 |101>（qubit0 在最低位）
+
+     result = grover(f, 3)        # 搜索唯一满足 f 的状态
+"""
+
+from .grover import mark_state
+
+
+def oracle(n_qubits):
+    """装饰器：把一个经典谓词 f(x) -> bool 变成 Grover 相位神谕。
+
+    f 接受整数 x（0 <= x < 2**n_qubits），返回 True 表示标记该状态。
+    所有满足 f(x)=True 的状态都会被施加 -1 相位。
+
+    返回的装饰器把 f 包装成 oracle(circuit) 回调，可直接传给 grover()，
+    也可传给 quantum_counting()（后者会读取其 .marked 属性）。
+
+    参数：
+        n_qubits: 谓词作用的量子比特数。
+    """
+    if not isinstance(n_qubits, int) or n_qubits < 1:
+        raise ValueError(f"n_qubits 必须是正整数，收到 {n_qubits!r}")
+
+    def decorator(f):
+        marked = tuple(x for x in range(2 ** n_qubits) if f(x))
+
+        def phase_oracle(circuit):
+            for x in marked:
+                mark_state(format(x, f"0{n_qubits}b"))(circuit)
+
+        phase_oracle.marked = marked
+        phase_oracle.n_qubits = n_qubits
+        phase_oracle.__name__ = getattr(f, "__name__", "oracle")
+        return phase_oracle
+
+    return decorator

quonic/algorithms/qaoa.py

@@ -0,0 +1,93 @@
+"""QAOA（量子近似优化算法）模板，求解 MaxCut 问题。
+
+给定无向图（边列表），用 p=1 层 QAOA 变分求最大割。
+
+示例：三角形图（3 个顶点、3 条边）
+
+    from quonic.algorithms import qaoa
+
+    edges = [(0, 1), (1, 2), (0, 2)]
+    result = qaoa.qaoa_maxcut(edges, 3)
+    print(result["cut"])   # 三角形最大割 = 2
+"""
+
+from ..result import Result
+from ..simulator import StatevectorSimulator
+
+
+def _pauli_z(i, j, n):
+    s = ["I"] * n
+    s[i] = "Z"
+    s[j] = "Z"
+    return "".join(s)
+
+
+def _qaoa_state(n, edges, p, params):
+    gammas = params[:p]
+    betas = params[p:]
+    sim = StatevectorSimulator(n)
+    for q in range(n):
+        sim.apply("h", (q,))
+    for layer in range(p):
+        # 代价层：exp(-i γ Z_i Z_j) = CX · Rz(2γ) · CX
+        for i, j in edges:
+            sim.apply("cx", (i, j))
+            sim.apply("rz", (j,), (2 * gammas[layer],))
+            sim.apply("cx", (i, j))
+        # 混合层：Rx(2β)
+        for q in range(n):
+            sim.apply("rx", (q,), (2 * betas[layer],))
+    return sim
+
+
+def qaoa_maxcut(edges, n_qubits, p=1, init_params=None, optimizer="COBYLA", maxiter=300,
+                record_history=False):
+    """变分求解给定图的 MaxCut。
+
+    参数：
+        edges: 边列表 [(i, j), ...]。
+        n_qubits: 顶点数。
+        p: QAOA 层数（默认 1）。
+        init_params: 初始参数（长度 2p），默认全 0.1。
+        optimizer / maxiter: 传给 scipy.optimize.minimize。
+        record_history: 为 True 时把每步能量记录进 metadata["history"]，
+            供 plot_energy_convergence 画收敛曲线（默认关闭）。
+
+    返回：Result（kind="value"），result.value 为近似最大割，
+    metadata 含 "params"（最优参数）、"energy"（Σ<ZiZj>）与可选 "history"。
+    """
+    try:
+        from scipy.optimize import minimize
+    except ImportError as e:
+        raise ImportError(
+            "使用 QAOA 需要安装 scipy：\n"
+            "    pip install 'quonic[algorithms]'\n"
+            "或： pip install scipy"
+        ) from e
+
+    if init_params is None:
+        init_params = [0.1] * (2 * p)
+
+    def cost(params):
+        sim = _qaoa_state(n_qubits, edges, p, params)
+        return sum(sim.expectation(_pauli_z(i, j, n_qubits)) for i, j in edges)
+
+    history = []
+    callback = None
+    if record_history:
+        def callback(xk):
+            history.append(float(cost(xk)))
+
+    result = minimize(
+        cost,
+        init_params,
+        method=optimizer,
+        options={"maxiter": maxiter},
+        callback=callback,
+    )
+    energy = float(result.fun)
+    cut = (len(edges) - energy) / 2.0
+    metadata = {"params": [float(x) for x in result.x], "energy": energy}
+    if record_history:
+        metadata["history"] = history
+    return Result.from_value(cut, **metadata)

quonic/algorithms/qpe.py

@@ -0,0 +1,55 @@
+"""量子相位估计（QPE）模板。
+
+估计单比特门 U = Rz(θ) 作用在 |1> 上的本征相位。
+
+Rz(θ)|1> = e^{iθ/2}|1>，所以本征相位 φ = θ/2。
+QPE 用 n 个相位比特估计 j，满足 j/2^n ≈ φ/(2π) = θ/(4π)。
+
+示例：
+    import math
+    from quonic.algorithms import qpe
+
+    result = qpe(math.pi, n_precision=3, shots=1024)
+    # Rz(π)|1> 相位 π/2，φ/(2π)=1/4，j≈2 -> 相位比特 "010"
+"""
+
+
+from ..backends import get_backend
+from ..ir import Circuit, GateOperation
+from ..qft import add_iqft
+
+
+def _add_crz(circuit, c, t, theta):
+    # 受控 Rz(theta)（控制 c，目标 t）
+    circuit.add(GateOperation("cx", (c, t)))
+    circuit.add(GateOperation("rz", (t,), (-theta / 2,)))
+    circuit.add(GateOperation("cx", (c, t)))
+    circuit.add(GateOperation("rz", (t,), (theta / 2,)))
+
+
+def _add_iqft(circuit, n):
+    # 逆量子傅里叶变换（qubit 0 = 最低位），委托给 qft 模块
+    add_iqft(circuit, list(range(n)))
+
+
+def qpe(theta, n_precision, shots=1024, backend="auto"):
+    """估计 Rz(theta) 作用在 |1> 上的本征相位。
+
+    参数：
+        theta: 单比特旋转角（弧度）。
+        n_precision: 相位估计的比特数。
+        shots / backend: 采样参数。
+
+    返回：Result（kind="counts"）。比特串最右侧 n_precision 位是相位估计，
+    其整数值 j 满足 j/2^n ≈ theta/(4π)（n = n_precision）。
+    """
+    n = n_precision
+    state_qubit = n
+    circuit = Circuit()
+    circuit.add(GateOperation("x", (state_qubit,)))
+    for j in range(n):
+        circuit.add(GateOperation("h", (j,)))
+    for j in range(n):
+        _add_crz(circuit, j, state_qubit, theta * (2 ** (n - 1 - j)))
+    _add_iqft(circuit, n)
+    return get_backend(backend).run(circuit, shots=shots)

quonic/algorithms/quantum_counting.py

@@ -0,0 +1,109 @@
+"""量子计数（quantum counting）模板。
+
+用 Grover 迭代 + 量子相位估计（QPE）估计满足神谕的解的个数 M。
+
+原理：Grover 算子 G 在 {|非解>, |解>} 子空间内旋转角度 2θ，其中
+sin²θ = M / N（N = 2^n）。QPE 估计 G 的本征相位 θ/π，从而反解出 M。
+
+示例：在 3 比特（N=8）中统计有多少个状态满足谓词
+
+    from quonic.algorithms import oracle, quantum_counting
+
+    @oracle(3)
+    def f(x):
+        return x & 1 == 0            # 偶数：共 4 个解
+
+    result = quantum_counting(f, 3)
+    print(result.value)              # 接近 4
+"""
+
+import math
+
+from ..backends import get_backend
+from ..ir import Circuit, GateOperation
+from ..result import Result
+from .qpe import _add_iqft
+
+
+def _marked_states(oracle, n_qubits):
+    if isinstance(oracle, str):
+        if len(oracle) != n_qubits:
+            raise ValueError(
+                f"标记比特串 '{oracle}' 长度 {len(oracle)} 与量子比特数 {n_qubits} 不一致"
+            )
+        return [int(oracle, 2)]
+    if hasattr(oracle, "marked"):  # @oracle 装饰器产物
+        if oracle.n_qubits != n_qubits:
+            raise ValueError(
+                f"神谕的量子比特数 {oracle.n_qubits} 与 n_qubits={n_qubits} 不一致"
+            )
+        return list(oracle.marked)
+    if callable(oracle):  # 裸谓词 f(x) -> bool
+        states = [x for x in range(2 ** n_qubits) if oracle(x)]
+        if not states:
+            raise ValueError("神谕没有标记任何状态，无法计数")
+        return states
+    raise TypeError("oracle 必须是标记比特串、@oracle 装饰器产物或谓词函数")
+
+
+def _add_controlled_oracle(circuit, control, search, marked):
+    n = len(search)
+    for x in marked:
+        bits = format(x, f"0{n}b")
+        for q in range(n):
+            if bits[n - 1 - q] == "0":
+                circuit.add(GateOperation("x", (search[q],)))
+        circuit.add(GateOperation("mcz", tuple([control] + search)))
+        for q in range(n):
+            if bits[n - 1 - q] == "0":
+                circuit.add(GateOperation("x", (search[q],)))
+
+
+def _add_controlled_diffusion(circuit, control, search):
+    for q in search:
+        circuit.add(GateOperation("h", (q,)))
+    for q in search:
+        circuit.add(GateOperation("x", (q,)))
+    circuit.add(GateOperation("mcz", tuple([control] + search)))
+    for q in search:
+        circuit.add(GateOperation("x", (q,)))
+    for q in search:
+        circuit.add(GateOperation("h", (q,)))
+
+
+def _add_controlled_grover(circuit, control, search, marked):
+    _add_controlled_oracle(circuit, control, search, marked)
+    _add_controlled_diffusion(circuit, control, search)
+
+
+def quantum_counting(oracle, n_qubits, t=None, backend="auto", shots=1024):
+    """估计满足神谕的解的个数 M。
+
+    参数：
+        oracle: 标记比特串、@oracle 装饰器产物或谓词 f(x)->bool。
+        n_qubits: 搜索空间量子比特数（N = 2**n_qubits）。
+        t: 计数量子比特数，默认 n_qubits + 1（越大估计越精确）。
+        backend / shots: 采样参数。
+
+    返回：Result（kind="value"），result.value 为 M 的估计值。
+    """
+    marked = _marked_states(oracle, n_qubits)
+    if t is None:
+        t = n_qubits + 1
+
+    search = list(range(t, t + n_qubits))
+    circuit = Circuit()
+    for q in range(t + n_qubits):
+        circuit.add(GateOperation("h", (q,)))
+
+    for j in range(t):
+        for _ in range(2 ** (t - 1 - j)):
+            _add_controlled_grover(circuit, j, search, marked)
+
+    _add_iqft(circuit, t)
+
+    result = get_backend(backend).run(circuit, shots=shots)
+    best = max(result.counts, key=result.counts.get)
+    j = int(best[-t:], 2)  # 最右侧 t 位是计数比特
+    m = 2 ** n_qubits * math.sin(math.pi * abs(j / 2 ** t - 0.5)) ** 2
+    return Result.from_value(m, j=j, t=t, counts=result.counts)