量子输运

unitarylab_algorithms.quantum_transport 提供 NEGFAlgorithm，从算法库 1.1.13 起加入。它使用非平衡格林函数（NEGF）方法描述连接左右半无限引线的矩形正方晶格器件，通过 UnitaryLab 内置 QSVT 求解器计算引线注入响应，再计算透射率、局域态密度（LDOS）和键电流。

安装与导入


pip install unitarylab unitarylab-algorithms kwant

直接依赖包括 NumPy、SciPy、Matplotlib、Kwant 和 UnitaryLab。Kwant 在 run() 内导入，运行前需准备好该依赖；本文不保证各平台都有可用的预编译安装包。


from unitarylab_algorithms import NEGFAlgorithm
# 等价类别入口：
from unitarylab_algorithms.quantum_transport import NEGFAlgorithm

最小示例


from tempfile import TemporaryDirectory
from unitarylab_algorithms import NEGFAlgorithm
 
with TemporaryDirectory() as output_dir:
    result = NEGFAlgorithm(algo_dir=output_dir).run(
        L=2, W=2, a=1.0, t=1.0, inverse_tolerance=2e-3,
    )
    print(result["transmission"])
    print(result["injection_residuals"])
    print(result["qasm_paths"])

临时目录退出后会删除输出；需要保留文件时改用持久目录。构造函数接受 text_mode="plain"、algo_dir=None，默认保存到当前工作目录下的 results/quantum_transport/negf/。

模块级 test(L=4, W=4, a=1.0, t=1.0, inverse_tolerance=2e-3) 从 unitarylab_algorithms.quantum_transport.negf 或其 algorithm 模块导入，使用 text_mode="legacy" 并返回同样的结果字典。

参数与模型

参数	默认值	含义
`L`	`4`	散射区 x 方向格点数，必须为至少 2 的整数，不能为布尔值
`W`	`4`	y 方向格点数及左右引线宽度，必须为至少 2 的整数，不能为布尔值
`a`	`1.0`	晶格常数；该模型建议使用正值，接口没有单独的正值校验
`t`	`1.0`	跃迁能标（eV）；该模型建议使用正值，接口没有单独的正值校验
`inverse_tolerance`	`2e-3`	有限数值且严格位于 `(0, 1)` 的倒数多项式相对误差容限

run() 仅接受上述五个算法参数，不接受自定义能量、Hamiltonian、backend、device、dtype 或 shots。内部固定使用 NumPy CPU、np.complex128，读取模拟态幅值而非有限 shots 统计。

格点 onsite 为 4*t，最近邻 hopping 为 -t。注入能量自动取横向前两个子带阈值的中点：

E_{m} = 2 t (1 - cos \frac{mπ}{W + 1}), ENERGY = \frac{E _{1} + E _{2}}{2} .

计算流程与误差

Kwant 构建散射区及引线，提供器件矩阵和引线自能；展宽矩阵只保存为界面局部块。
组装 $A = E I - H_{C} - Σ_{L} - Σ_{R}$ ，从 $Γ_{L / R} = i (Σ_{L / R} - Σ_{L / R}^{†})$ 分解得到注入向量 $C_{L}, C_{R}$ 。
将求解矩阵展开为稠密数组并补齐到二次幂，构建一次 QSVT 主体；各通道用包含输入态制备的实际线路分别执行。
读取辅助位全为零的分块，恢复右端向量范数、缩放及复相位，得到 $A X_{L} = C_{L}$ 、 $A X_{R} = C_{R}$ 的近似解。
独立计算注入方程相对残差，再经典计算可观测量：

T = ∥ C_{R}^{†} X_{L} ∥_{F}^{2}, LDOS_{i} = \frac{\sum _{a} ∣ ( X _{L} ) _{ia} ∣ ^{2} + \sum _{a} ∣ ( X _{R} ) _{ia} ∣ ^{2}}{2 π} .

键电流沿用 2 * imag(H_C[i, j] * vdot(X_L[i], X_L[j]))，按 Kwant fsyst.graph 的有向键顺序返回。该值不是以 SI 安培表示的有限偏压电流；本实现没有偏压窗口积分、占据权重或 SI 电流前因子。

inverse_tolerance 校准一次 SDK 内部 epsilon，用 20001 个谱网格点及实际奇异值检查倒数多项式误差。inverse_polynomial_error 是该检查得到的最大相对误差，不是严格的连续谱误差证明。最终方程残差独立保存在 injection_residuals，不以同一容限作为失败断言。矩阵在当前数值精度下必须可逆；没有传播通道或数值校准失败时会抛出异常。

返回字段

结果继承共享基类返回约定；成功时 status="ok"，并包含以下字段：

字段	含义
`circuit_path`、`circuit`	第一个实际注入线路的 SVG 路径及对象，包含输入态制备和 QSVT 主体
`plot`	生成文件的 `format`、`filename` 列表；文件名相对于结果目录
`circuits`、`circuit_paths`	按左侧、右侧注入通道顺序排列的全部实际线路和 SVG 路径
`qasm_paths`	成功导出的 QASM2 文件路径
`qasm_export_errors`	导出不受支持的记录，每项含线路名 `circuit` 和异常文字 `reason`
`ENERGY`	自动计算的注入能量
`left_channels`、`right_channels`	保留的左右注入通道数
`transmission`	透射率
`injection_residuals`	各通道的 `norm(A @ x - b) / norm(b)`
`epsilon`、`inverse_polynomial_error`	校准后的 SDK 参数和倒数多项式误差
`scaling_factor`、`rhs_norms`	SDK 缩放因子与各注入向量原始范数
`system_size`	散射区原始矩阵维数 `L*W`
`ldos`	按散射区格点顺序排列的 LDOS 数组
`bond_current`	按有向键顺序排列的键电流数组

返回字典包含 NumPy 数组和 Circuit 对象，不是可直接 JSON 序列化的纯数据字典。status="ok" 表示工作流完成，不保证残差满足指定容限，也不保证每条线路都成功导出 QASM。

文件与使用限制

negf_result.txt：输入、日志和结果摘要。
kwant_square_system.png、kwant_square_ldos.png、kwant_square_current.png：器件结构、LDOS 与键电流图。
negf_circuit.svg、negf_circuit_2.svg 等：各通道实际执行的线路。
negf_circuit.qasm、negf_circuit_2.qasm 等：仅在对应线路成功导出 QASM2 时生成。

QASM2 通过 to_qasm2(transpile=True) 导出。按当前 SDK 的 Nagy 分解尺寸限制，补齐后的系统维数需满足 N <= 32（即 L*W <= 32）才能满足该导出尺寸要求；这不是 run() 的格点数上限。默认 4×4 器件在此尺寸范围内。其他门或版本限制仍可能使导出失败。

导出时的 NotImplementedError 按通道写入 qasm_export_errors，该通道不加入 qasm_paths；数值结果、全部实际线路和 SVG 仍保留，算法继续返回成功。其他异常仍正常抛出。QASM2 导出会省略无控制的全局相位，若要从导出线路的逐个复幅值恢复响应，应考虑该相位。

SVG 可能受 SDK 默认绘图层数限制而截断，不能据此判断完整门数。矩阵虽以稀疏形式组装，求解路径仍包含稠密线性代数与全态模拟；增加格点数或收紧容限可能显著增加计算及导出成本，不能据此声称端到端量子加速。